Use recursive autosummary (glotaran#403)

* Updated needed dependencies

* Updated module template to use autosummary's  new recursive option

* Removed now obsolete api-codcs-up-to-date CI test 

and removed old api building part

* Removed now obsolete files

* Fixed broken citation error

* Added doc artifact upload

* Explicitly set the template for class attributes

since autosummary didn't pick it up

* Removed now obsolete api generation hack artifacts

Author: s-weigand

.github/workflows/CI_CD_actions.yml

@@ -36,8 +36,12 @@ jobs:
         run: pip freeze
       - name: Build docs
         run: |
-          python docs/source/generate_api_doc.py
           make --directory=docs clean html
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs
+          path: docs/build/html
 
   docs-links:
     runs-on: ubuntu-latest
@@ -56,37 +60,12 @@ jobs:
         run: pip freeze
       - name: Check doc links
         run: |
-          python docs/source/generate_api_doc.py
           make --directory=docs clean linkcheck $@ | tee linkcheck-output.txt
           exit ${PIPESTATUS[0]}
       - name: Linkcheck summary
         if: ${{ always() }}
         run: cat linkcheck-output.txt | grep -E "(\(line.*\)|writing output)"
 
-  api-docs-up-to-date:
-    runs-on: ubuntu-latest
-    needs: [test]
-    steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python 3.7
-        uses: actions/setup-python@v1
-        with:
-          python-version: 3.7
-      - name: Install dependencies
-        run: |
-          python -m pip install -U pip
-          pip install .
-      - name: Show installed packages
-        run: pip freeze
-      - name: Check if api docs are outdated
-        run: |
-          mv docs/source/user_documentation/api_documentation.rst current_api_docs.rst
-          python docs/source/generate_api_doc.py
-          diff -qywBd current_api_docs.rst docs/source/user_documentation/api_documentation.rst
-      - name: Fix instructions
-        if: failure()
-        run: echo run 'python docs/source/generate_api_doc.py' locally to fix this issue
-
   test:
     runs-on: ${{ matrix.os }}
     needs: lint

docs/Makefile

@@ -35,9 +35,6 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf $(API_TOCTREE_DIR)/*
 
-api_doc:
-	$(PYTHON_TO_USE) $(SOURCEDIR)/generate_api_doc.py
-
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/source/_templates/api_documentation_template.rst

@@ -0,0 +1,4 @@
+{{ name  | escape | underline }}
+
+.. autoattribute:: {{ fullname }}
+    :noindex:

docs/source/_templates/autosummary/attribute.rst

@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/base.rst

@@ -14,40 +14,39 @@
     .. rubric:: Attributes Summary
 
     .. autosummary::
-       :toctree: 
+       :toctree:
+       :template: autosummary/attribute.rst
     {% for item in attributes %}
         ~{{name}}.{{ item }}
     {%- endfor %}
 
     {% endif %}
     {% endblock %}
 
-    {% if '__init__' in methods %}
-        {% set caught_result = methods.remove('__init__') %}
-    {% endif %}
-
 
     {% block methods_summary %}
     {% if methods %}
 
     .. rubric:: Methods Summary
 
     .. autosummary::
-        :toctree: 
+        :toctree:
         :nosignatures:
 
     {% for item in methods %}
+      {% if not item.endswith("__init__") %}
         ~{{ name }}.{{ item }}
+      {% endif %}
     {%- endfor %}
 
-    {% block methods_documentation %}
-    {% if methods %}
-
-    .. rubric:: Methods Documentation
 
     {% endif %}
     {% endblock %}
 
+    {% block methods_documentation %}
+    {% if methods %}
+
+    .. rubric:: Methods Documentation
 
     {% endif %}
     {% endblock %}

docs/source/_templates/autosummary/class.rst

@@ -1,72 +1,93 @@
-{% extends "known_packages.rst" %}
 {% block module %}
-{{ fullname | replace("glotaran.", "") | escape | underline}}
-{#{% set reduced_name={child_modules} %}#}
+{{ name  | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
 .. automodule:: {{ fullname }}
 
-    {% if fullname in known_packages %}
-    .. rubric:: Submodules
 
-    .. autosummary::
-        {% for item in child_modules %}
-            {% if item.startswith( fullname + ".") %}
-                {{ item }}
-            {% endif %}
-        {%- endfor %}
-    {% endif %}
 
-    {% block functions %}
-    {% if functions %}
+{% block modules %}
+  {% if modules %}
+
+  .. rubric:: Modules
+
+  .. autosummary::
+    :toctree: {{ name }}
+    :recursive:
+
+    {% for item in modules %}
+      {% if not item.endswith("test") %}
+        {{ item }}
+      {% endif %}
+
+    {%- endfor %}
+
+  {% endif %}
+
+{% endblock %}
+
+
+{% block functions %}
+  {% if functions %}
 
 Functions
 ---------
 
-    .. rubric:: Summary
+  .. rubric:: Summary
+
+  .. autosummary::
+      :toctree: {{ name }}
+      :nosignatures:
 
-    .. autosummary::
-        :toctree: {{ fullname | replace("glotaran.", "") | replace(".", "/") }}/functions
-        :nosignatures:
-        {% for item in functions %}
+      {% for item in functions %}
         {{ item }}
-        {%- endfor %}
-    {% endif %}
-    {% endblock %}
+      {%- endfor %}
 
-    {% block classes %}
-    {% if classes %}
+  {% endif %}
+
+{% endblock %}
+
+{% block classes %}
+  {% if classes %}
 
 Classes
 -------
 
-    .. rubric:: Summary
+  .. rubric:: Summary
+
+  .. autosummary::
+      :toctree: {{ name }}
+      :nosignatures:
 
-    .. autosummary::
-        :toctree: {{ fullname | replace("glotaran.", "") | replace(".", "/") }}/classes
-        :nosignatures:
-    {% for item in classes %}
+      {% for item in classes %}
         {{ item }}
-    {%- endfor %}
-    {% endif %}
-    {% endblock %}
+      {%- endfor %}
+
+  {% endif %}
+
+{% endblock %}
 
-    {% block exceptions %}
-    {% if exceptions %}
+
+{% block exceptions %}
+  {% if exceptions %}
 
 Exceptions
 ----------
 
-    .. rubric:: Exception Summary
+  .. rubric:: Exception Summary
+
+  .. autosummary::
+      :toctree: {{ name }}
+      :nosignatures:
 
-    .. autosummary::
-        :toctree: {{ fullname | replace("glotaran.", "") | replace(".", "/") }}/exceptions
-    {% for item in exceptions %}
+      {% for item in exceptions %}
         {{ item }}
-    {%- endfor %}
-    {% endif %}
-    {% endblock %}
+      {%- endfor %}
+
+  {% endif %}
+
+{% endblock %}
 
 
-{% endblock %}
+{% endblock %}