169 improve apidoc generation (#342)

* Remove autodoc and apidoc in favor of autoapi.
* No need to manually edit api documentation ever again.
* Display not perfect but reasonable for now. See #341

.github/workflows/main.yml

@@ -92,17 +92,16 @@ jobs:
         run: ./codetools/mypy/check.sh ${{ matrix.package }}
 
   docs:
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11"]
     runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v3
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: 3.11
       - name: install_revolve2
         run: ./dev_install.sh
+      - name: setup_graphviz
+        uses: ts-graphviz/setup-graphviz@v1
       - name: sphinx
         run: make -C docs html
       - name: deploy

codetools/black/check.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/black/fix.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/darglint/check.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/isort/check.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/isort/fix.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/mypy/check_all.sh

@@ -7,4 +7,4 @@ cd "$(dirname "$0")"
 while read -r package; do
     echo "$package:"
     mypy --config-file ./mypy.ini "../../$package"
-done < ../packages.txt
+done < ../../packages.txt

codetools/pydocstyle/check.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/pyflakes/check.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

codetools/sort_all/fix.sh

@@ -2,7 +2,7 @@
 
 cd "$(dirname "$0")"
 
-packages=$(tr '\n' ' ' < ../packages.txt)
+packages=$(tr '\n' ' ' < ../../packages.txt)
 
 cd ../..
 

docs/Makefile

@@ -1,35 +1,12 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SPHINXAPIDOC  ?= sphinx-apidoc
-APIDOCARGS    ?= -o source/api_reference --implicit-namespaces --module-first --separate --tocfile index --doc-project 'API Reference' --maxdepth 1 --templatedir $(THIS_DIR)/source/apidoc_template
+SPHINXOPTS    = -W --keep-going
+SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 
-THIS_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
-
-# Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-apidoc:
-	@$(SPHINXAPIDOC) ../ci_group/revolve2 $(APIDOCARGS)
-	@$(SPHINXAPIDOC) ../experimentation/revolve2 $(APIDOCARGS)
-	@$(SPHINXAPIDOC) ../modular_robot/revolve2 $(APIDOCARGS)
-	@$(SPHINXAPIDOC) ../modular_robot_simulation/revolve2 $(APIDOCARGS)
-	@$(SPHINXAPIDOC) ../simulation/revolve2 $(APIDOCARGS)
-	@$(SPHINXAPIDOC) ../simulators/mujoco_simulator/revolve2 $(APIDOCARGS)
-
-apidoc_overwrite:
-	APIDOCARGS="$(APIDOCARGS) -f" $(MAKE) apidoc
-
-.PHONY: help Makefile apidoc apidoc_overwrite
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile

docs/requirements.txt

@@ -1,2 +1,3 @@
-sphinx==6.2.1
-sphinx-rtd-theme==1.2.0
+sphinx==7.2.6
+sphinx-rtd-theme==1.3.0
+sphinx-autoapi==3.0.0

docs/source/_templates/autoapi/python/module.rst

@@ -0,0 +1,114 @@
+{% if not obj.display %}
+:orphan:
+
+{% endif %}
+:py:mod:`{{ obj.name.split('.')[-1] }}`
+=========={{ "=" * obj.name|length }}
+
+.. py:module:: {{ obj.name }}
+
+{% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|indent(3) }}
+
+{% endif %}
+
+{% block subpackages %}
+{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+{% if visible_subpackages %}
+Subpackages
+-----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 3
+
+{% for subpackage in visible_subpackages %}
+   {{ subpackage.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block submodules %}
+{% set visible_submodules = obj.submodules|selectattr("display")|list %}
+{% if visible_submodules %}
+Submodules
+----------
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+{% for submodule in visible_submodules %}
+   {{ submodule.short_name }}/index.rst
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% block content %}
+{% if obj.all is not none %}
+{% set visible_children = obj.children|selectattr("short_name", "in", obj.all)|list %}
+{% elif obj.type is equalto("package") %}
+{% set visible_children = obj.children|selectattr("display")|list %}
+{% else %}
+{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
+{% endif %}
+{% if visible_children %}
+{{ obj.type|title }} Contents
+{{ "-" * obj.type|length }}---------
+
+{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
+{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
+{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
+{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
+{% block classes scoped %}
+{% if visible_classes %}
+Classes
+~~~~~~~
+
+.. autoapisummary::
+
+{% for klass in visible_classes %}
+   {{ klass.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block functions scoped %}
+{% if visible_functions %}
+Functions
+~~~~~~~~~
+
+.. autoapisummary::
+
+{% for function in visible_functions %}
+   {{ function.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+
+{% block attributes scoped %}
+{% if visible_attributes %}
+Attributes
+~~~~~~~~~~
+
+.. autoapisummary::
+
+{% for attribute in visible_attributes %}
+   {{ attribute.id }}
+{% endfor %}
+
+
+{% endif %}
+{% endblock %}
+{% endif %}
+{% for obj_item in visible_children %}
+{{ obj_item.render()|indent(0) }}
+{% endfor %}
+{% endif %}
+{% endblock %}