Documentation generation from C comments

C programming, build, interpreter/VM.
Target audience: MicroPython Developers.
Post Reply
BramPeeters
Posts: 49
Joined: Wed Jan 31, 2018 3:10 pm

Documentation generation from C comments

Post by BramPeeters » Wed Apr 11, 2018 9:46 am

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

User avatar
pythoncoder
Posts: 3420
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: Documentation generation from C comments

Post by pythoncoder » Thu Apr 12, 2018 6:42 am

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.
Peter Hinch

BramPeeters
Posts: 49
Joined: Wed Jan 31, 2018 3:10 pm

Re: Documentation generation from C comments

Post by BramPeeters » Sat Apr 14, 2018 12:10 am

Too bad :(

Thanks for the clarification !

User avatar
pythoncoder
Posts: 3420
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: Documentation generation from C comments

Post by pythoncoder » Sat Apr 14, 2018 11:18 am

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.
Peter Hinch

Post Reply