docs: Generate documentation from the kconfig files #3608
Conversation
btashton
force-pushed
the
kconfig-docs
branch
6 times, most recently
from
259f1aa to
5f2e0c8
Compare
|
@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 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: |
|
BTW, why 16000 files? Do we have 16000 config vars?? |
| {% if node.include_path %} | ||
| Included via: {% for filename, linenr in node.include_path %}``{{filename}}:{{linenr}}``{% if not loop.last %} -> {% endif %}{% endfor %} | ||
| {% endif %} | ||
| Menu path: (Top) -> {% for node_p in top_to_node(node) %}{% if node_p.prompt %}{{node_p.prompt[0]}}{% else %}{{kconfiglib.standard_sc_expr_str(node_p.item)}}{% endif %}{% if not loop.last %} -> {% endif %}{% endfor %} |
There was a problem hiding this comment.
Use :menuselection: for nicer rendering as explain here: https://nuttx.apache.org/docs/latest/contributing/documentation.html#user-indications
There was a problem hiding this comment.
This is different. This is menu as in Kconfig menu
There was a problem hiding this comment.
I have used it for Kconfig in other parts: https://nuttx.apache.org/docs/latest/quickstart/configuring.html#configuring
|
|
||
| At ``{{node.filename}}:{{node.linenr}}`` | ||
| {% if node.include_path %} | ||
| Included via: {% for filename, linenr in node.include_path %}``{{filename}}:{{linenr}}``{% if not loop.last %} -> {% endif %}{% endfor %} |
There was a problem hiding this comment.
We could probably use :file: for filenames and later generate links to GitHub (to master or appropriate tag).
There was a problem hiding this comment.
I like this idea. Not quite sure how we would handle this cross repo, but something to think about.
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. |
|
@hartmannathan this was my stab at this feature |
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