Add package API documentation generation

Add generation of the API documentation for akkudoktoreos and akkudoktoreosserver packages. The API documentation is generated by the Sphinx autosummary extension. Signed-off-by: Bobby Noelte <[email protected]>
Akkudoktor-EOS · Oct 10, 2024 · c9ac4a8 · c9ac4a8
1 parent 59dcf8c
commit c9ac4a8
Show file tree

Hide file tree

Showing 7 changed files with 145 additions and 5 deletions.
diff --git a/.gitignore b/.gitignore
@@ -66,6 +66,9 @@ coverage.xml
 .pytest_cache/
 cover/
 
+# Documentation generation
+_autosummary/
+
 # Translations
 *.mo
 *.pot

diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 # Define the targets
-.PHONY: help venv pip install dist test docker-run docs clean
+.PHONY: help venv pip install dist test docker-run docs read-docs clean
 
 # Default target
 all: help
@@ -11,8 +11,9 @@ help:
 	@echo "  pip        - Install dependencies from requirements.txt."
 	@echo "  pip-dev    - Install dependencies from requirements-dev.txt."
 	@echo "  install    - Install EOS in editable form (development mode) into virtual environment."
-	@echo "  docker-run - Run entire setup on docker
+	@echo "  docker-run - Run entire setup on docker."
 	@echo "  docs       - Generate HTML documentation (in build/docs/html/)."
+	@echo "  read-docs  - Read HTML documentation in your browser."
 	@echo "  run        - Run flask_server in the virtual environment (needs install before)."
 	@echo "  dist       - Create distribution (in dist/)."
 	@echo "  clean      - Remove generated documentation, distribution and virtual environment."
@@ -50,6 +51,11 @@ docs: pip-dev
 	.venv/bin/sphinx-build -M html docs build/docs
 	@echo "Documentation generated to build/docs/html/."
 
+# Target to read the HTML documentation
+read-docs: docs
+	@echo "Read the documentation in your browser"
+	.venv/bin/python -m webbrowser build/docs/html/index.html
+
 # Clean target to remove generated documentation, distribution and virtual environment
 clean:
 	@echo "Cleaning virtual env, distribution and documentation directories"

diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -0,0 +1,33 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: autosummary/class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: autosummary/module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/akkudoktoreos/api.rst b/docs/akkudoktoreos/api.rst
@@ -0,0 +1,16 @@
+..
+    Copyright (c) 2024 Bobby Noelte
+    SPDX-License-Identifier: Apache-2.0
+
+.. _akkudoktoreos_api:
+
+Akkudoktor EOS API
+==================
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: autosummary/module.rst
+   :recursive:
+
+   akkudoktoreos
+   akkudoktoreosserver
diff --git a/docs/conf.py b/docs/conf.py
@@ -6,9 +6,6 @@
 import sys
 from pathlib import Path
 
-# Make source file directories available to sphinx
-sys.path.insert(0, str(Path("..", "src").resolve()))
-
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -46,3 +43,21 @@
     "logo_only": False,
     "titles_only": True,
 }
+
+
+# -- Options for autodoc -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
+# Make source file directories available to sphinx
+sys.path.insert(0, str(Path("..", "src").resolve()))
+
+autodoc_default_options = {
+    "members": "var1, var2",
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+}
+
+# -- Options for autosummary -------------------------------------------------
+autosummary_generate = True
diff --git a/docs/index.rst b/docs/index.rst
@@ -15,3 +15,4 @@ Akkudoktor EOS documentation
    akkudoktoreos/about
    develop/getting_started
    develop/CONTRIBUTING
+   akkudoktoreos/api