MicroPython Forum (Archive)

Posted: **Sat Jun 06, 2020 7:37 pm**

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!

Posted: **Mon Jun 08, 2020 9:32 pm**

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.

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',
]

Russ

Posted: **Tue Jun 09, 2020 1:31 pm**

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.

Posted: **Sun Jul 26, 2020 10:01 pm**

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

Posted: **Mon Jul 27, 2020 8:37 am**

Hi pawamoy, thanks for the hint!

Posted: **Mon Jul 27, 2020 12:37 pm**

I got the following error:

Code: Select all

mkdocstrings.handlers.CollectionError: module 'lib' has no attribute 'helpers'

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

Code: Select all

## Documentation for Helper
::: lib.helpers

mkdocs.yml

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()

any idea why it does not find this module?

Posted: **Fri Aug 07, 2020 9:58 am**

If you add the

Code: Select all

lib

directory to

Code: Select all

sys.path

, then you can write

Code: Select all

::: helpers

directly.

MicroPython Forum (Archive)

Generating autodocs for upython

Generating autodocs for upython

Re: Generating autodocs for upython

Re: Generating autodocs for upython

Re: Generating autodocs for upython

Re: Generating autodocs for upython

Re: Generating autodocs for upython

Re: Generating autodocs for upython