What / Why¶
Advantages : they bring the richness of the MicroPython documentation to Pylance. This includes function and method parameters and descriptions, the module and class constants for all documented library modules.
How docstubs are generated¶
The documentation stubs are generated using the
stubber get-docstubs command.
Read the Micropython library documentation files and use them to build stubs that can be used for static typechecking using a custom-built parser to read and process the micropython RST files
This will generate :
Python modules (
<module.py>), one for each
The module docstring is based on the module header in the .rst file
Function parameters and types based on documentation As the parameter documentaion is sometimes rather abigious or imprecise, the parameters definities are cleaned up based on a hand tuned algoritm
The function docstring is based on the function description in the .rst file
The return type of a function is based on phrases used in the documentation, with an override table for functions with insufficient documented information to determine the return type.
The class docstring is based on the Class description in the .rst file
The init parameters are based on the documentation for the class As the parameter documentaion is sometimes rather abigious or imprecise, the parameters definities are cleaned up based on a hand tuned algoritm
init docstring is based on the Class description in the .rst file
Method parameters and types based are based on the documentation in the .rst file As the parameter documentaion is sometimes rather abigious or imprecise, the parameters definities are cleaned up based on a hand tuned algoritm
The method docstring is based on the method description in the .rst file
The return type of a method is based on phrases used in the documentation, with an override table for functions with insufficient documented information to determine the return type.
Method decorators @classmethod and @staticmethod are generated based on the use of
py:classmethodin the documentation. ref: https://sphinx-tutorial.readthedocs.io/cheatsheet/
Method parameter names
clsare used accordingly.
Tries to determine the return type by parsing the docstring.
Imperative verbs used in docstrings have a strong correlation to return -> None
Recognizes documented Generators, Iterators, Callable
Coroutines are identified based tag “This is a Coroutine”. Then if the return type was Foo, it will be transformed to : Coroutine[Foo]
A static Lookup list is used for a few methods/functions for which the return type cannot be determined from the docstring.
add NoReturn to a few functions that never return ( stop / deepsleep / reset )
if no type can be detected the type
Lookup tables :¶
contains return types for functions and methods
“module.[class.].function” : ( “type”, probability)
if no type has been determined, and the docstring starts with one of these verbs, then assume the return type is None
Add additional imports to some modules to allow one module to import other supporting modules
currently only used for
manual fixes needed for parameters ( micropython v.16 & v1.17)
used to clean up the parameter strings before further interpetation using search and replace
List of classes and their parent classes that should be added to the class definition. The documentation contains no clear references of the parent classes so these can only be added based on a (manual) lookup table
Note: The parent class Exeptions is determined based on the rst hint
py:exceptionand the Class Name.
The generated stub files (
.py) are formatted using
black and checked for validity using
Note: black on python 3.7 does not like some function defs, this is not treated as an error.
def sizeof(struct, layout_type=NATIVE, /) -> int:
Ordering of inter-dependent classes in the same module¶
Classes are frequently documented in a different order than thery need to be declared in a source file. To accomodate for this the source code is re-ordered to avoid forward references in the code. The code for this is located in :
Add GLUE imports to allow specific modules to import specific others.¶
This is based on the
MODULE_GLUE table to support some modules that need to import other modules or classes.
Literals / constants¶
- documentation contains repeated vars with the same indentation - Module level: .. code-block:: .. data:: IPPROTO_UDP IPPROTO_TCP - class level: .. code-block:: .. data:: Pin.IRQ_FALLING Pin.IRQ_RISING Pin.IRQ_LOW_LEVEL Pin.IRQ_HIGH_LEVEL Selects the IRQ trigger type. - literals documented using a wildcard are added as comments only
Repeats of definitions in the rst file for similar functions or literals
CONSTANTS ( module and Class level )