aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/_templates/autoapi/module.rst121
-rw-r--r--doc/conf.py38
-rw-r--r--doc/prolog.inc4
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