Documentation generation from C comments

C programming, build, interpreter/VM.
Target audience: MicroPython Developers.
Post Reply
BramPeeters
Posts: 54
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: 5956
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
Index to my micropython libraries.

BramPeeters
Posts: 54
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: 5956
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
Index to my micropython libraries.

Post Reply