nuttx
nuttx copied to clipboard
apache
docs: Generate documentation from the kconfig files
Summary
This generates documentation as reference that can be used from the Kconfig files.
This is not ready to merge this is just for feedback on the idea. I am still trying to figure out what the best way to make this work is. Building all of this take a long time for sphinx on the first pass as it generates ~16000 files. Other projects that do something similar just create a stub file for the references that can be used for normal building and only when you want to build the final documentation package do you generate the full rendering of the pages, I think that would be very reasonable.
The output looks something like this with all the CONFIG_ as references that you can click
@btashton - I think this is great! It also has as side benefit of us putting more effort into more detailed help in the Kconfig files. Sometimes even a one line of explanation can save lots of grepping.
This is a great idea! I think it also will spot many Kconfig entry that are missing Help information!
There is a tool at tools/mkconfigvars.sh and tools/kconfig2html.c that I used to use to generate online configuration variable documentation. It would generate a 10Mb or so HTML file with collapsible hyperlinked TOC and cross-referenced dependencies.
There is a tool at tools/mkconfigvars.sh and tools/kconfig2html.c that I used to use to generate online configuration variable documentation. It would generate a 10Mb or so HTML file with collapsible hyperlinked TOC and cross-referenced dependencies.
There is still a very old generated HTML file online: https://cwiki.apache.org/confluence/display/NUTTX/Configuration+Variables
That should be removed. It is way out of date. I would update that file on each release so that it reflects the current state of configuration variables.
Nice. I always thought this would be good to have, accompanied with a sphinx role such as :kconfig:<config var> which would link to the documentation of the variable. Maybe we can look into how to achieve that.
BTW, together with the CMake system I intend to have a specific documentation section such as "Build System". I imagine This section be a sibling of this one. I tried to think of a top-level section that could group these and other related sections but I can't come up with an appropriate name. I thought about something like "Developer Guide" (which also allows for other sections explaining how to add new board, app, arch, etc.). What do you think?
Nice. I always thought this would be good to have, accompanied with a sphinx role such as :kconfig:
<config var>which would link to the documentation of the variable. Maybe we can look into how to achieve that.
This already does that you just have to do :option:`CONFIG_FOO` and it will create the reference for you.
This was actually my main motivation because I want to link to this from the board documentation so we can stop documenting the same things over and over with stale information.
As for the 16000 files yes there are that many configuration variable. Most of them are arch and chip specific.