How to provide documentation/help for a user C module? Docstrings don't show up in help()

[moefear85]

Hi,

I realized in normal python, I can add a docstring at the beginning of a function, and when the user types help(my_function), the docstring will show up, so I can explain what the function does and what the parameters represent. But this doesn't work on mpy, it only shows the type and address/id of the object in question.

I'm new to writing shareable open source, and have no idea in general how people best provide documentation for their projects. Usually fancy projects provide their own website, and simple ones use readme.md in github. I know there is readthedocs for usual python packages, and theoretically it can be used for micropython, but are there other ways? Which is the best and how to do it? The easiest for me would be somehow exposing docstrings to the user, such that the user types help(module_name) and gets everything they need to know shown there. Maybe there can even be a script that converts that to html or md files that I can then upload to github?

[andrewleech]

In most cases help isn't really enabled / used in micropython as the text takes up quite a lot of flash space (relative to bytecode).

I think in particular it doesn't even exist for functions (as you've found) but can be enabled as a build option for modules.

The official micropython docs are

Built with Sphinx using a theme provided by Read the Docs.

Currently though micropython-lib modules have notes in matching readme at best, maybe some example scripts.

I usually just put some details in a readme (or often nothing at all ... )

[moefear85]

I guess I'll have to learn sphinx then. Seems itself well documented. thx.

[russhughes]

I use sphinx to document my MicroPython projects. You can find an example in my https://github.com/russhughes/wt32sc01py github repo. I use sys.path.insert in the sphinx conf.py to add my MicroPython code and autodoc_mock_imports for the MicroPython libraries.

For user C modules I cheat. Sphinx wants to create documenation on the user C module code itself, and not the python functions it provides. I use comments with /// before each line of my "doctstring" and extract them using grep ^/// code.c to pull them out for a README.md or to create .rst files for sphinx.

[moefear85]

I just noticed, the REPL explicitly says: "... type help(obj) for more information". What's that help for if it is intended to only be an alias for type() for binary size reasons? Where are the actual help strings located?