Merge pull request #2283 from Paebbels/paebbels/doc

Sphinx updates

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