diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_templates/autoapi/module.rst | 121 | ||||
| -rw-r--r-- | doc/conf.py | 38 | ||||
| -rw-r--r-- | doc/prolog.inc | 4 |
3 files changed, 97 insertions, 66 deletions
diff --git a/doc/_templates/autoapi/module.rst b/doc/_templates/autoapi/module.rst index e359b32af..0ad8469a8 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 }} @@ -22,21 +26,31 @@ .. currentmodule:: {{ node.name }} {##} -.. #----------------------------------- -{##} {%- if node.variables %} + **Variables** -{##} + {% for item, obj in node.variables.items() -%} - :py:data:`{{ item }}` + {#{ obj|summary }#} {% endfor -%} {%- endif -%} +{%- if node.functions %} + +**Functions** + +{% for item, obj in node.functions.items() -%} +- :py:func:`{{ item }}`: + {{ obj|summary }} + +{% endfor -%} +{%- endif -%} {%- if node.exceptions %} -{##} + **Exceptions** -{##} + {% for item, obj in node.exceptions.items() -%} - :py:exc:`{{ item }}`: {{ obj|summary }} @@ -44,11 +58,10 @@ {% endfor -%} {%- endif -%} - {%- if node.classes %} -{##} + **Classes** -{##} + {% for item, obj in node.classes.items() -%} - :py:class:`{{ item }}`: {{ obj|summary }} @@ -56,26 +69,22 @@ {% endfor -%} {%- endif -%} +{%- block variables -%} +{%- if node.variables %} -{%- if node.functions %} -{##} -**Functions** -{##} -{% for item, obj in node.functions.items() -%} -- :py:func:`{{ item }}`: - {{ obj|summary }} +--------------------- -{% endfor -%} -{%- endif -%} +**Variables** +{#% for item, obj in node.variables.items() -%} +- :py:data:`{{ item }}` +{% endfor -%#} -{%- block variables -%} -{%- if node.variables %} {% for item, obj in node.variables.items() %} .. autodata:: {{ item }} :annotation: - .. code-block:: guess + .. code-block:: text {{ obj|pprint|indent(6) }} {##} @@ -83,60 +92,68 @@ {%- endif -%} {%- endblock -%} +{%- block functions -%} +{%- if node.functions %} + +--------------------- + +**Functions** + +{% for item in node.functions %} +.. autofunction:: {{ item }} +{##} +{%- endfor -%} +{%- endif -%} +{%- endblock -%} {%- block exceptions -%} {%- if node.exceptions %} -.. #----------------------------------- +--------------------- + +**Exceptions** + +{#% for item, obj in node.exceptions.items() -%} +- :py:exc:`{{ item }}`: + {{ obj|summary }} + +{% endfor -%#} {% for item in node.exceptions %} .. autoexception:: {{ item }} - :members: - :private-members: - :inherited-members: - :undoc-members: -{##} + .. rubric:: Inheritance .. inheritance-diagram:: {{ item }} -{##} - .. rubric:: Members + :parts: 1 {##} {%- endfor -%} {%- endif -%} {%- endblock -%} - {%- block classes -%} {%- if node.classes %} -.. #----------------------------------- +--------------------- + +**Classes** + +{#% for item, obj in node.classes.items() -%} +- :py:class:`{{ item }}`: + {{ obj|summary }} + +{% endfor -%#} {% for item in node.classes %} .. autoclass:: {{ item }} :members: :private-members: - :undoc-members: + :special-members: :inherited-members: -{##} + :exclude-members: __weakref__ + .. rubric:: Inheritance .. inheritance-diagram:: {{ item }} -{##} - .. rubric:: Members -{##} -{%- endfor -%} -{%- endif -%} -{%- endblock -%} - - -{%- block functions -%} -{%- if node.functions %} - -.. #----------------------------------- - -**Functions** - -{% for item in node.functions %} -.. autofunction:: {{ item }} + :parts: 1 {##} {%- endfor -%} {%- endif -%} diff --git a/doc/conf.py b/doc/conf.py index 7bbb1e054..3ed641b56 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' # ============================================================================== @@ -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', ] @@ -202,7 +200,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 +213,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" # ============================================================================== @@ -230,6 +223,17 @@ 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 # ============================================================================== # If true, `todo` and `todoList` produce output, else they produce nothing. @@ -238,6 +242,12 @@ todo_link_only = True # ============================================================================== +# Sphinx.Ext.Coverage +# ============================================================================== +coverage_show_missing_items = True + + +# ============================================================================== # Sphinx.Ext.ExtLinks # ============================================================================== extlinks = { 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 <hr /> + +.. role:: pycode(code) + :language: python + :class: highlight |