Open HackXIt opened 1 month ago
Just for anyone else stumbling upon this, the import or module errors are actually easily dealt with via the usage of mock
import sys
if sys.implementation.name == "micropython": # Regular import when inside micropython
import lvgl as lv
else: # Mocked import when run through pdoc
import mock # Mock library
from .mock.lvgl import lv # Fake module folder containing source files with necessary mocked defines
Problem Description
I am using micropython in my project and it is fairly easy and straightforward to add docstrings.
However, it is not possible to use
pdoc
in all cases, as sometimes the source code requires imports that pdoc cannot resolve, since they might be C modules compiled into the micropython binary.Proposal
To circumvent the stated problem, it would be nice if one could modify the behavior of pdoc to ignore certain imports and unknown modules.
Possibly in a similar way, which linters use via comments:
Alternatives
If the behavior can't be circumvented, it would be nice if one could "feed" pdoc with the relevant docstrings extracted by micropython. This could simply be in the form of some JSON, YAML or similar file format. Such a file could easily be generated by micropython, in a desired format.
The information read from the file could then be parsed into pdoc to generate the relevant documentation.
Additional context
I was not able to use pdoc on my micropython project based on LVGL, due to the following errors:
Console output
```shell $ pdoc src pdoc server ready at http://localhost:8080 Warn: Couldn't import src.design_parser: Traceback (most recent call last): File "/home/rini-debian/git-stash/lvgl-ui-detector/lvgl_ui_generator_v2/.venv/lib/python3.11/site-packages/pdoc/extract.py", line 218, in load_module return importlib.import_module(module) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/lib/python3.11/importlib/__init__.py", line 126, in import_module return _bootstrap._gcd_import(name[level:], package, level) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "