From 7f37dadcf570795169a24bf75f972949b067401b Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Wed, 22 Jun 2022 09:00:42 +0200 Subject: Updated autoapi template. (cherry picked from commit 4977150c62f61abd9740f6b0386dc2340b13dd07) --- doc/_templates/autoapi/module.rst | 129 +++++++++++++++----------------------- 1 file changed, 50 insertions(+), 79 deletions(-) diff --git a/doc/_templates/autoapi/module.rst b/doc/_templates/autoapi/module.rst index e359b32af..5c64bbec6 100644 --- a/doc/_templates/autoapi/module.rst +++ b/doc/_templates/autoapi/module.rst @@ -1,4 +1,9 @@ -{{ node.name }} +.. # Template modified by Patrick Lehmann + * removed automodule on top, because private members are activated for autodoc (no doubled documentation). + * Made sections like 'submodules' bold text, but no headlines to reduce number of ToC levels. + +=={{ '=' * node.name|length }}== +``{{ node.name }}`` =={{ '=' * node.name|length }}== .. automodule:: {{ node.name }} @@ -7,10 +12,9 @@ {%- block modules -%} {%- if subnodes %} -.. #----------------------------------- -{##} **Submodules** + .. toctree:: {% for item in subnodes %} {{ item.name }} @@ -21,122 +25,89 @@ {##} .. currentmodule:: {{ node.name }} {##} - -.. #----------------------------------- -{##} -{%- if node.variables %} -**Variables** -{##} -{% for item, obj in node.variables.items() -%} -- :py:data:`{{ item }}` -{% endfor -%} -{%- endif -%} - - -{%- if node.exceptions %} -{##} -**Exceptions** -{##} -{% for item, obj in node.exceptions.items() -%} -- :py:exc:`{{ item }}`: - {{ obj|summary }} - -{% endfor -%} -{%- endif -%} - - -{%- if node.classes %} -{##} -**Classes** -{##} -{% for item, obj in node.classes.items() -%} -- :py:class:`{{ item }}`: - {{ obj|summary }} - -{% endfor -%} -{%- endif -%} - - +{%- block functions -%} {%- if node.functions %} -{##} + **Functions** -{##} + {% for item, obj in node.functions.items() -%} - :py:func:`{{ item }}`: {{ obj|summary }} {% endfor -%} -{%- endif -%} - -{%- block variables -%} -{%- if node.variables %} -{% for item, obj in node.variables.items() %} -.. autodata:: {{ item }} - :annotation: - - .. code-block:: guess - - {{ obj|pprint|indent(6) }} +{% for item in node.functions %} +.. autofunction:: {{ item }} {##} {%- endfor -%} {%- endif -%} {%- endblock -%} +{%- block classes -%} +{%- if node.classes %} -{%- block exceptions -%} -{%- if node.exceptions %} +**Classes** + +{% for item, obj in node.classes.items() -%} +- :py:class:`{{ item }}`: + {{ obj|summary }} -.. #----------------------------------- +{% endfor -%} -{% for item in node.exceptions %} -.. autoexception:: {{ item }} +{% for item in node.classes %} +.. autoclass:: {{ item }} :members: :private-members: + :special-members: :inherited-members: - :undoc-members: -{##} + :exclude-members: __weakref__ + .. rubric:: Inheritance .. inheritance-diagram:: {{ item }} -{##} - .. rubric:: Members + :parts: 1 {##} {%- endfor -%} {%- endif -%} {%- endblock -%} +{%- block exceptions -%} +{%- if node.exceptions %} -{%- block classes -%} -{%- if node.classes %} +**Exceptions** -.. #----------------------------------- +{% for item, obj in node.exceptions.items() -%} +- :py:exc:`{{ item }}`: + {{ obj|summary }} + +{% endfor -%} + +{% for item in node.exceptions %} +.. autoexception:: {{ item }} -{% for item in node.classes %} -.. autoclass:: {{ item }} - :members: - :private-members: - :undoc-members: - :inherited-members: -{##} .. rubric:: Inheritance .. inheritance-diagram:: {{ item }} -{##} - .. rubric:: Members + :parts: 1 {##} {%- endfor -%} {%- endif -%} {%- endblock -%} +{%- block variables -%} +{%- if node.variables %} -{%- block functions -%} -{%- if node.functions %} +**Variables** -.. #----------------------------------- +{% for item, obj in node.variables.items() -%} +- :py:data:`{{ item }}` +{% endfor -%} -**Functions** +{% for item, obj in node.variables.items() %} +.. autodata:: {{ item }} + :annotation: -{% for item in node.functions %} -.. autofunction:: {{ item }} + .. code-block:: text + + {{ obj|pprint|indent(6) }} {##} {%- endfor -%} {%- endif -%} -- cgit v1.2.3 From e284c9245a01e1709f59dec260cef53f4fb76530 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 24 Jun 2022 23:19:22 +0200 Subject: Improved autoapi template. (cherry picked from commit 8d85d97998a9f0694889d0ddd579e7d9f247ab3d) --- doc/_templates/autoapi/module.rst | 106 +++++++++++++++++++++++++++----------- 1 file changed, 76 insertions(+), 30 deletions(-) diff --git a/doc/_templates/autoapi/module.rst b/doc/_templates/autoapi/module.rst index 5c64bbec6..0ad8469a8 100644 --- a/doc/_templates/autoapi/module.rst +++ b/doc/_templates/autoapi/module.rst @@ -25,7 +25,17 @@ {##} .. currentmodule:: {{ node.name }} {##} -{%- block functions -%} + +{%- if node.variables %} + +**Variables** + +{% for item, obj in node.variables.items() -%} +- :py:data:`{{ item }}` + {#{ obj|summary }#} +{% endfor -%} +{%- endif -%} + {%- if node.functions %} **Functions** @@ -35,15 +45,19 @@ {{ obj|summary }} {% endfor -%} +{%- endif -%} -{% for item in node.functions %} -.. autofunction:: {{ item }} -{##} -{%- endfor -%} +{%- if node.exceptions %} + +**Exceptions** + +{% for item, obj in node.exceptions.items() -%} +- :py:exc:`{{ item }}`: + {{ obj|summary }} + +{% endfor -%} {%- endif -%} -{%- endblock -%} -{%- block classes -%} {%- if node.classes %} **Classes** @@ -53,18 +67,40 @@ {{ obj|summary }} {% endfor -%} +{%- endif -%} -{% for item in node.classes %} -.. autoclass:: {{ item }} - :members: - :private-members: - :special-members: - :inherited-members: - :exclude-members: __weakref__ +{%- block variables -%} +{%- if node.variables %} - .. rubric:: Inheritance - .. inheritance-diagram:: {{ item }} - :parts: 1 +--------------------- + +**Variables** + +{#% for item, obj in node.variables.items() -%} +- :py:data:`{{ item }}` +{% endfor -%#} + +{% for item, obj in node.variables.items() %} +.. autodata:: {{ item }} + :annotation: + + .. code-block:: text + + {{ obj|pprint|indent(6) }} +{##} +{%- endfor -%} +{%- endif -%} +{%- endblock -%} + +{%- block functions -%} +{%- if node.functions %} + +--------------------- + +**Functions** + +{% for item in node.functions %} +.. autofunction:: {{ item }} {##} {%- endfor -%} {%- endif -%} @@ -73,13 +109,15 @@ {%- block exceptions -%} {%- if node.exceptions %} +--------------------- + **Exceptions** -{% for item, obj in node.exceptions.items() -%} +{#% for item, obj in node.exceptions.items() -%} - :py:exc:`{{ item }}`: {{ obj|summary }} -{% endfor -%} +{% endfor -%#} {% for item in node.exceptions %} .. autoexception:: {{ item }} @@ -92,22 +130,30 @@ {%- endif -%} {%- endblock -%} -{%- block variables -%} -{%- if node.variables %} +{%- block classes -%} +{%- if node.classes %} -**Variables** +--------------------- -{% for item, obj in node.variables.items() -%} -- :py:data:`{{ item }}` -{% endfor -%} +**Classes** -{% for item, obj in node.variables.items() %} -.. autodata:: {{ item }} - :annotation: +{#% for item, obj in node.classes.items() -%} +- :py:class:`{{ item }}`: + {{ obj|summary }} - .. code-block:: text +{% endfor -%#} - {{ obj|pprint|indent(6) }} +{% for item in node.classes %} +.. autoclass:: {{ item }} + :members: + :private-members: + :special-members: + :inherited-members: + :exclude-members: __weakref__ + + .. rubric:: Inheritance + .. inheritance-diagram:: {{ item }} + :parts: 1 {##} {%- endfor -%} {%- endif -%} -- cgit v1.2.3 From ef330ba87ea2fc808e1043f8cab4662565257e67 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 24 Jun 2022 23:19:41 +0200 Subject: Updated Sphinx configuration. (cherry picked from commit fe702ec6fc634c72d98e174d4fba5b9aa014aa45) --- doc/conf.py | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 7bbb1e054..f1ce09fd9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -63,7 +63,7 @@ exclude_patterns = [ ] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'stata-dark' +pygments_style = 'manni' # ============================================================================== @@ -202,7 +202,7 @@ extensions = [ # Sphinx.Ext.InterSphinx # ============================================================================== intersphinx_mapping = { - 'python': ('https://docs.python.org/3.6/', None), + 'python': ('https://docs.python.org/3', None), 'cosim': ('https://ghdl.github.io/ghdl-cosim', None), 'poc': ('https://poc-library.readthedocs.io/en/release', None), 'vhdlmodel': ('https://vhdl.github.io/pyVHDLModel', None), @@ -215,12 +215,7 @@ intersphinx_mapping = { # ============================================================================== # see: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration autodoc_member_order = "bysource" # alphabetical, groupwise, bysource -# autodoc_default_options = { -# "members": True, -# 'undoc-members': True, -# #'private-members': True, -# 'inherited-members': True, -# } +autodoc_typehints = "both" # ============================================================================== @@ -229,6 +224,17 @@ autodoc_member_order = "bysource" # alphabetical, groupwise, bysource graphviz_output_format = "svg" +# ============================================================================== +# Sphinx.Ext.Inheritance_Diagram +# ============================================================================== +inheritance_node_attrs = { +# "shape": "ellipse", +# "fontsize": 14, +# "height": 0.75, + "color": "dodgerblue1", + "style": "filled" +} + # ============================================================================== # Sphinx.Ext.ToDo # ============================================================================== @@ -237,6 +243,12 @@ todo_include_todos = True todo_link_only = True +# ============================================================================== +# Sphinx.Ext.Coverage +# ============================================================================== +coverage_show_missing_items = True + + # ============================================================================== # Sphinx.Ext.ExtLinks # ============================================================================== -- cgit v1.2.3 From 3e0ccf6230010bdcf0f49c777a06dc1aa168abf4 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 24 Jun 2022 23:58:04 +0200 Subject: Removed/disabled customized Sphinx/BTD extensions. (cherry picked from commit d5ff8ffe2e56f614b1c942913796a2733a68aab7) --- doc/conf.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index f1ce09fd9..3ed641b56 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -174,26 +174,24 @@ extensions = [ # Standard Sphinx extensions 'sphinx.ext.autodoc', 'sphinx.ext.extlinks', + 'sphinx.ext.inheritance_diagram', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', -# 'sphinx.ext.graphviz', + 'sphinx.ext.graphviz', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', # BuildTheDocs extensions 'btd.sphinx.autoprogram', - 'btd.sphinx.graphviz', - 'btd.sphinx.inheritance_diagram', +# 'btd.sphinx.graphviz', +# 'btd.sphinx.inheritance_diagram', # Other extensions # 'recommonmark', 'exec', -# 'DocumentMember', 'sphinx_fontawesome', 'sphinx_autodoc_typehints', - - # local extensions (patched) 'autoapi.sphinx', ] -- cgit v1.2.3 From 2cfa55afd77e9d561a44f6adba827eadfbc87c22 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 24 Jun 2022 23:58:18 +0200 Subject: Added pycode role. (cherry picked from commit cf52f1ccf5491c8dca8cf97b156a2d0d29c004d9) --- doc/prolog.inc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/prolog.inc b/doc/prolog.inc index 7297d9939..6c89551e4 100644 --- a/doc/prolog.inc +++ b/doc/prolog.inc @@ -12,3 +12,7 @@ .. |hr| raw:: html
+ +.. role:: pycode(code) + :language: python + :class: highlight -- cgit v1.2.3