Is there a way to generate auto docs from upython code like we normally do with python?
Using Sphinx auto docs or mkdocstrings is not working as standard python is used to import the modules to be documented.
This leads to some issues if some modules are not importable (such as "import machine")...
Any advice/workaround or tips would be very much appreciated!
Generating autodocs for upython
Re: Generating autodocs for upython
I used the Sphinx sphinx.ext.autodoc extension to document my last MicroPython project. In my conf.py file I added the projects lib directory using sys.path.insert and autodoc_mock_imports for the rest of the modules.
Russ
Code: Select all
sys.path.insert(0, os.path.abspath('../../lib')) # add my lib modules
autodoc_mock_imports = [
'machine',
'board',
'st7789',
'network',
'servo',
'esp',
'uos',
'btree',
]
Re: Generating autodocs for upython
Thanks for your answer. That works great with Sphinx!
It would also be nice to be able to do this using MkDocs. I did not found a way yet. Keep you posted.
It would also be nice to be able to do this using MkDocs. I did not found a way yet. Keep you posted.
Re: Generating autodocs for upython
You can change sys.path and mock packages in mkdocstrings as well:
Code: Select all
plugins:
- mkdocstrings:
handlers:
python:
setup_commands:
- import sys
- from unittest.mock import MagicMock as mock
- sys.path.insert(0, os.path.abspath('../../lib'))
- sys.modules['machine'] = mock()
- sys.modules['board'] = mock()
# etc
Re: Generating autodocs for upython
Hi pawamoy, thanks for the hint!
Last edited by ltmerlin on Mon Jul 27, 2020 12:38 pm, edited 1 time in total.
Re: Generating autodocs for upython
I got the following error:
I added my lib dir which contains a helpers.py file which I want to document, but it does not seem to find it.
docs/helpers.md
mkdocs.yml
any idea why it does not find this module?
Code: Select all
mkdocstrings.handlers.CollectionError: module 'lib' has no attribute 'helpers'
docs/helpers.md
Code: Select all
## Documentation for Helper
::: lib.helpers
Code: Select all
- mkdocstrings:
handlers:
python:
setup_commands:
- import sys
- from unittest.mock import MagicMock as mock
- sys.path.append("lib")
- sys.modules['machine'] = mock()
- sys.modules['board'] = mock()
Re: Generating autodocs for upython
If you add the directory to , then you can write directly.
Code: Select all
lib
Code: Select all
sys.path
Code: Select all
::: helpers