Using better-apidoc to generate templated package and module documentation;...

Using better-apidoc to generate templated package and module documentation; added generation templates

.gitlab-ci.yml

@@ -31,9 +31,9 @@ pages:
   script:
   - pip install sphinx
   - pip install sphinx_rtd_theme
+  - pip install better-apidoc
   - pip install numpydoc
-  - sphinx-apidoc -l -e -d 3 -o docs/source/mod nifty4
-  - sphinx-build -b html docs/source/ docs/build/
+  - sh docs/generate.sh
   - mv docs/build/ public/
   artifacts:
     paths:

docs/generate.sh

 rm -rf docs/build docs/source/mod
-sphinx-apidoc -l -e -d 3 -o docs/source/mod nifty4
+better-apidoc -l -e -d 2 -t docs/generation-templates -o docs/source/mod nifty4
 sphinx-build -b html docs/source/ docs/build/
-

docs/generation-templates/module.rst

+{% if name %}
+{{ name }}
+{% for item in range(8 + name|length) -%}={%- endfor %}
+{% else %}
+{{ fullname }}
+{% for item in range(8 + fullname|length) -%}={%- endfor %}
+({{ fullname }} module)
+{% endif %}
+
+.. currentmodule:: {{ fullname }}
+
+.. automodule:: {{ fullname }}
+    {% if members -%}
+    :members: {{ members|join(", ") }}
+    :undoc-members:
+    :show-inheritance:
+    :member-order: bysource
+
+    Summary
+    -------
+    {% if doc:%}
+    {{doc}}
+    {% endif %}
+
+    {%- if exceptions %}
+
+    Exceptions:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in exceptions %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+    {%- if classes %}
+
+    Classes:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in classes %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+    {%- if functions %}
+
+    Functions:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in functions %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+    {%- endif %}
+
+    {%- if data %}
+
+    Data:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in data %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+{% if all_refs %}
+    ``__all__``: {{ all_refs|join(", ") }}
+{%- endif %}
+
+
+{% if members %}
+    Reference
+    ---------
+
+{%- endif %}
\ No newline at end of file

docs/generation-templates/package.rst

+{% if name %}
+{{ name }}
+{% for item in range(8 + name|length) -%}={%- endfor %}
+({{ fullname }} package)
+
+{% else %}
+{{ fullname }}
+{% for item in range(8 + fullname|length) -%}={%- endfor %}
+({{ fullname }} package)
+{% endif %}
+
+.. automodule:: {{ fullname }}
+    {% if members -%}
+    :members: {{ members|join(", ") }}
+    :undoc-members:
+    :show-inheritance:
+    {%- endif %}
+
+
+
+
+    {% if submodules %}
+    Submodules:
+
+    .. toctree::
+        :maxdepth: 1
+        {% for item in submodules %}
+        {{ fullname }}.{{ item }}
+        {%- endfor %}
+    {%- endif -%}
+
+    {% if subpackages %}
+
+
+    Subpackages:
+
+    .. toctree::
+        :maxdepth: 1
+        {% for item in subpackages %}
+        {{ fullname }}.{{ item }}
+        {%- endfor %}
+
+
+    {%- endif %}
+
+    {% if members or doc %}
+    Summary
+    -------
+    {% if doc:%}
+    {{doc}}
+    {% endif %}
+
+    {%- if exceptions %}
+
+    Exceptions:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in exceptions %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+    {%- if classes %}
+
+    Classes:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in classes %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+    {%- if functions %}
+
+    Functions:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in functions %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+    {%- endif %}
+
+    {%- if data %}
+
+    Data:
+
+    .. autosummary::
+        :nosignatures:
+        {% for item in data %}
+        {{ item }}
+        {%- endfor %}
+    {%- endif %}
+
+{% if all_refs %}
+    ``__all__``: {{ all_refs|join(", ") }}
+{%- endif %}
+
+
+{% if members %}
+    Reference
+    ---------
+
+{%- endif %}
\ No newline at end of file

docs/source/code.rst

@@ -5,7 +5,7 @@ The NIFTy code is divided in the concepts Spaces, Fields, Operators and Minimiza
 
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Concepts
    :glob:
 

docs/source/concepts/field.rst

@@ -4,6 +4,7 @@ Fields
 Description of Fields
 
 .. toctree::
+    :maxdepth: 1
     :caption: Types of Fields
 
     Field                           <../mod/nifty4.field>

docs/source/concepts/minimization.rst

@@ -4,6 +4,7 @@ Minimization
 Description of Minimization
 
 .. toctree::
+    :maxdepth: 1
     :caption: Minimization Concepts
 
     Conjugate Gradient                      <../mod/nifty4.minimization.conjugate_gradient>

docs/source/concepts/operators.rst

@@ -4,6 +4,7 @@ Operators
 Description of Operators
 
 .. toctree::
+    :maxdepth: 1
     :caption: Types of Operators
 
     Adjoint                             <../mod/nifty4.operators.adjoint_operator>

docs/source/concepts/spaces.rst

@@ -4,6 +4,7 @@ Spaces
 Description of Spaces
 
 .. toctree::
+    :maxdepth: 1
     :caption: Types of Spaces
 
     DOF                             <../mod/nifty4.spaces.dof_space>

nifty4/spaces/__init__.py

+"""
+Sample documentation for spaces. (or any other package) This will be displayed under Summary section of module documentation
+"""

nifty4/spaces/dof_space.py

@@ -16,6 +16,10 @@
 # NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
 # and financially supported by the Studienstiftung des deutschen Volkes.
 
+"""
+Sample documentation for DOF space. (or any other module). This will be displayed under Summary section of module documentation
+"""
+
 import numpy as np
 from .structured_domain import StructuredDomain