Docstring to Markdown

[Tico06]

Hi There,

I am looking for a way to convert the Docstrings to Markdown files with Micropython, or from Micropython files.

Thanks and regards,

Eric.

[Josverl]

Care to explain the question behind?

As Micropython does not actually have Docstrings __doc__currently
.

Are you perhaps referring to the online documentation, or the Docstrings that are part of the micropython-stubs ?

[Tico06]

Yes sure. I want to document my own code and from my point of view the best area is in the code itself. I want to export my documentation from the source for sharing out of the code. Existing cpython solutions don't work or I was not able to do. Thx

[corranwebster]

The standard CPython solution is Sphinx, which doesn't use Markdown, but instead uses RestructuredText, which is similar in concept (it's a plaintext markup), but generally more powerful. Micropython is close enough to Python that Sphinx-based tooling generally works, with some tweaks. For automatic API documentation (ie. pulling things from docstrings) I have successfully used both AutoAPI and AutoSummary to extract docstrings from MicroPython code (I tend to use NumPy-style docstrings for my code, so I also use the Napoleon plugin).

The key tweak for Sphinx auto-documentation is to ensure that you mock Micropython library modules that don't exist in Python - add something like the following to the sphinx conf.py:

autodoc_mock_imports = [
    "micropython",
    "machine",
    "framebuf",
]

The key with all of these solutions is that you need a Python environment with these tools to run over your MicroPython codebase. So getting things working looks something like:

• set up a Python virtual environment (or use conda or whatever)
• install Sphinx and any plugins you need
• do Sphinx quickstart to get a basic document structure
• edit the conf.py to set up auto-documentation on your codebase

If you are strongly tied to using Markdown as a requirement (as opposed to any lightweight text-based markup), Sphinx can be configured to parse Markdown, and there is PydocMarkdown which is a Markdown-based alternative to Sphinx. I have not used either, either with CPython or Micropython, so I can't give any further pointers.

[Tico06]

Thanks a lot for your answer.
I think I can accommodate with Sphinx. I'll have look.
Eric.

[mdaeron]

You can look into pdoc. It generates static html from docstrings and understands markdown. You will probably need to run it from cpython, targeting your micropython code. Hope this helps.

[Tico06]

Thanks, I'll have look.