MicroPython Forum (Archive)

Hi,

I was wondering how the documentation is generated for C 'drivers', eg pin.c
The end result i can see eg at https://docs.micropython.org/en/latest/ ... b.Pin.html, and apparently a document generation tool sphinx is used.

Now i see 'formatted' comments partially matching this in eg \ports\stm32\pin.c
Eg:
/// \method value([value])
/// Get or set the digital logic level of the pin:
///
/// - With no argument, return 0 or 1 depending on the logic level of the pin.
/// - With `value` given, set the logic level of the pin. `value` can be
/// anything that converts to a boolean. If it converts to `True`, the pin
/// is set high, otherwise it is set low.

But some text is not present in the C file at all such as the entire 'Pin.init(mode, pull=Pin.PULL_NONE, af=-1) ' descirption, which just has
// init(mode, pull=None, af=-1, *, value, alt)
in the code.

The only place where the full description is present seems to be docs/library/pyb.Pin.rst. So this seems to be the input file for sphinx ?

So is this file maintained separately from the c code ?
Or is it generated from the c code (with which tool and where does the text that is not present in C comes from then ?)

Regards
Bram

I suspect this is something from the past which was tried and abandoned. In practice documentation is maintained by raising pull requests against the .rst files.

Too bad

Thanks for the clarification !

I think there are good reasons for this. MicroPython has grown to support multiple platforms and the docs vary between these, so I suspect auto-generation would no longer work properly.