You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by GitBox <gi...@apache.org> on 2021/04/26 08:43:11 UTC

[GitHub] [incubator-nuttx] btashton opened a new pull request #3608: docs: Generate documentation from the kconfig files

btashton opened a new pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608


   ## 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
   
   ![image](https://user-images.githubusercontent.com/173245/116054484-9138ec80-a630-11eb-9c4f-50a1bd1e50f8.png)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
btashton commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826945844


   > 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.
   
   As for the 16000 files yes there are that many configuration variable. Most of them are arch and chip specific.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] patacongo commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
patacongo commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826852597


   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.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on a change in pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#discussion_r620429784



##########
File path: Documentation/_kconfig/helper.jinja
##########
@@ -0,0 +1,56 @@
+{% macro help(sc) -%}
+Help
+====
+{% for node in sc.nodes -%}
+{% if node.help %}
+
+.. parsed-literal::
+
+    {{node.help|indent(4)}}
+{% endif %}
+{% endfor %}
+{%- endmacro %}
+{%- macro direct_dep(sc) -%}
+{% if sc.direct_dep == sc.kconfig.y %}
+{% else %}
+Direct Dependencies
+===================
+
+{{expr_str(sc.direct_dep)}}
+{% endif %}
+{%- endmacro %}
+{%- macro defaults(sc, choice) -%}
+Defaults
+========
+{% if sc.defaults %}
+{%- for value, cond in sc.orig_defaults %}
+- {{expr_str(value)}}{% if cond != sc.kconfig.y %} if {{expr_str(cond)}}{% endif %}
+{%- endfor %}
+{% else %}
+No defaults defined. Implicitly defined to {% if choice %}the first (visible) choice option.{% elif sc.orig_type in [kconfiglib.BOOL, kconfiglib.TRISTATE] %}``n``.{% else %}the empty string.{% endif %}
+{% endif %}
+{%- endmacro %}
+{%- macro kconfig_definition(sc) -%}
+Kconfig Definitions
+===================
+
+.. highlight:: kconfig
+
+{% for node in sc.nodes %}
+
+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 %}

Review comment:
       I like this idea. Not quite sure how we would handle this cross repo, but something to think about. 




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] davids5 commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
davids5 commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826833072


   @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 an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] acassis commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
acassis commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826845052


   This is a great idea! I think it also will spot many Kconfig entry that are missing Help information!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#discussion_r620420024



##########
File path: Documentation/_kconfig/helper.jinja
##########
@@ -0,0 +1,56 @@
+{% macro help(sc) -%}
+Help
+====
+{% for node in sc.nodes -%}
+{% if node.help %}
+
+.. parsed-literal::
+
+    {{node.help|indent(4)}}
+{% endif %}
+{% endfor %}
+{%- endmacro %}
+{%- macro direct_dep(sc) -%}
+{% if sc.direct_dep == sc.kconfig.y %}
+{% else %}
+Direct Dependencies
+===================
+
+{{expr_str(sc.direct_dep)}}
+{% endif %}
+{%- endmacro %}
+{%- macro defaults(sc, choice) -%}
+Defaults
+========
+{% if sc.defaults %}
+{%- for value, cond in sc.orig_defaults %}
+- {{expr_str(value)}}{% if cond != sc.kconfig.y %} if {{expr_str(cond)}}{% endif %}
+{%- endfor %}
+{% else %}
+No defaults defined. Implicitly defined to {% if choice %}the first (visible) choice option.{% elif sc.orig_type in [kconfiglib.BOOL, kconfiglib.TRISTATE] %}``n``.{% else %}the empty string.{% endif %}
+{% endif %}
+{%- endmacro %}
+{%- macro kconfig_definition(sc) -%}
+Kconfig Definitions
+===================
+
+.. highlight:: kconfig
+
+{% for node in sc.nodes %}
+
+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 %}
+{% 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 %}

Review comment:
       Use :menuselection: for nicer rendering as explain here: https://nuttx.apache.org/docs/latest/contributing/documentation.html#user-indications




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#discussion_r620421473



##########
File path: Documentation/_kconfig/helper.jinja
##########
@@ -0,0 +1,56 @@
+{% macro help(sc) -%}
+Help
+====
+{% for node in sc.nodes -%}
+{% if node.help %}
+
+.. parsed-literal::
+
+    {{node.help|indent(4)}}
+{% endif %}
+{% endfor %}
+{%- endmacro %}
+{%- macro direct_dep(sc) -%}
+{% if sc.direct_dep == sc.kconfig.y %}
+{% else %}
+Direct Dependencies
+===================
+
+{{expr_str(sc.direct_dep)}}
+{% endif %}
+{%- endmacro %}
+{%- macro defaults(sc, choice) -%}
+Defaults
+========
+{% if sc.defaults %}
+{%- for value, cond in sc.orig_defaults %}
+- {{expr_str(value)}}{% if cond != sc.kconfig.y %} if {{expr_str(cond)}}{% endif %}
+{%- endfor %}
+{% else %}
+No defaults defined. Implicitly defined to {% if choice %}the first (visible) choice option.{% elif sc.orig_type in [kconfiglib.BOOL, kconfiglib.TRISTATE] %}``n``.{% else %}the empty string.{% endif %}
+{% endif %}
+{%- endmacro %}
+{%- macro kconfig_definition(sc) -%}
+Kconfig Definitions
+===================
+
+.. highlight:: kconfig
+
+{% for node in sc.nodes %}
+
+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 %}

Review comment:
       We could probably use :file: for filenames and later generate links to GitHub (to master or appropriate tag).




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton edited a comment on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
btashton edited a comment on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826945844


   > 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.
   
   As for the 16000 files yes there are that many configuration variable. Most of them are arch and chip specific.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826941545


   BTW, why 16000 files? Do we have 16000 config vars??


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton edited a comment on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
btashton edited a comment on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826945844


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


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
v01d commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826940771


   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?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] btashton commented on a change in pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
btashton commented on a change in pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#discussion_r620421229



##########
File path: Documentation/_kconfig/helper.jinja
##########
@@ -0,0 +1,56 @@
+{% macro help(sc) -%}
+Help
+====
+{% for node in sc.nodes -%}
+{% if node.help %}
+
+.. parsed-literal::
+
+    {{node.help|indent(4)}}
+{% endif %}
+{% endfor %}
+{%- endmacro %}
+{%- macro direct_dep(sc) -%}
+{% if sc.direct_dep == sc.kconfig.y %}
+{% else %}
+Direct Dependencies
+===================
+
+{{expr_str(sc.direct_dep)}}
+{% endif %}
+{%- endmacro %}
+{%- macro defaults(sc, choice) -%}
+Defaults
+========
+{% if sc.defaults %}
+{%- for value, cond in sc.orig_defaults %}
+- {{expr_str(value)}}{% if cond != sc.kconfig.y %} if {{expr_str(cond)}}{% endif %}
+{%- endfor %}
+{% else %}
+No defaults defined. Implicitly defined to {% if choice %}the first (visible) choice option.{% elif sc.orig_type in [kconfiglib.BOOL, kconfiglib.TRISTATE] %}``n``.{% else %}the empty string.{% endif %}
+{% endif %}
+{%- endmacro %}
+{%- macro kconfig_definition(sc) -%}
+Kconfig Definitions
+===================
+
+.. highlight:: kconfig
+
+{% for node in sc.nodes %}
+
+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 %}
+{% 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 %}

Review comment:
       This is different. This is menu as in Kconfig menu 




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] patacongo commented on pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
patacongo commented on pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#issuecomment-826854895


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


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-nuttx] v01d commented on a change in pull request #3608: docs: Generate documentation from the kconfig files

Posted by GitBox <gi...@apache.org>.
v01d commented on a change in pull request #3608:
URL: https://github.com/apache/incubator-nuttx/pull/3608#discussion_r620423679



##########
File path: Documentation/_kconfig/helper.jinja
##########
@@ -0,0 +1,56 @@
+{% macro help(sc) -%}
+Help
+====
+{% for node in sc.nodes -%}
+{% if node.help %}
+
+.. parsed-literal::
+
+    {{node.help|indent(4)}}
+{% endif %}
+{% endfor %}
+{%- endmacro %}
+{%- macro direct_dep(sc) -%}
+{% if sc.direct_dep == sc.kconfig.y %}
+{% else %}
+Direct Dependencies
+===================
+
+{{expr_str(sc.direct_dep)}}
+{% endif %}
+{%- endmacro %}
+{%- macro defaults(sc, choice) -%}
+Defaults
+========
+{% if sc.defaults %}
+{%- for value, cond in sc.orig_defaults %}
+- {{expr_str(value)}}{% if cond != sc.kconfig.y %} if {{expr_str(cond)}}{% endif %}
+{%- endfor %}
+{% else %}
+No defaults defined. Implicitly defined to {% if choice %}the first (visible) choice option.{% elif sc.orig_type in [kconfiglib.BOOL, kconfiglib.TRISTATE] %}``n``.{% else %}the empty string.{% endif %}
+{% endif %}
+{%- endmacro %}
+{%- macro kconfig_definition(sc) -%}
+Kconfig Definitions
+===================
+
+.. highlight:: kconfig
+
+{% for node in sc.nodes %}
+
+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 %}
+{% 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 %}

Review comment:
       I have used it for Kconfig in other parts: https://nuttx.apache.org/docs/latest/quickstart/configuring.html#configuring




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org