Generating autodocs for upython

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
Post Reply
ltmerlin
Posts: 39
Joined: Fri Jun 28, 2019 12:34 pm

Generating autodocs for upython

Post by ltmerlin » 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!

User avatar
russ_h
Posts: 88
Joined: Thu Oct 03, 2019 2:26 am
Contact:

Re: Generating autodocs for upython

Post by russ_h » 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

ltmerlin
Posts: 39
Joined: Fri Jun 28, 2019 12:34 pm

Re: Generating autodocs for upython

Post by ltmerlin » 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.

pawamoy
Posts: 2
Joined: Sun Jul 26, 2020 9:56 pm

Re: Generating autodocs for upython

Post by pawamoy » 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

ltmerlin
Posts: 39
Joined: Fri Jun 28, 2019 12:34 pm

Re: Generating autodocs for upython

Post by ltmerlin » Mon Jul 27, 2020 8:37 am

Hi pawamoy, thanks for the hint!
Last edited by ltmerlin on Mon Jul 27, 2020 12:38 pm, edited 1 time in total.

ltmerlin
Posts: 39
Joined: Fri Jun 28, 2019 12:34 pm

Re: Generating autodocs for upython

Post by ltmerlin » 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?

pawamoy
Posts: 2
Joined: Sun Jul 26, 2020 9:56 pm

Re: Generating autodocs for upython

Post by pawamoy » 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.

Post Reply