Add API documentation generation and use Markdown (#160)

* 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]>

* Enable Google style source commenting and documentation generation.

Enable automatic documentation generation from Google style docstrings in the source.

Signed-off-by: Bobby Noelte <[email protected]>

* Check Google style source commenting.

Check Google style commenting by the appropriate ruff rules.

Commenting is _NOT_ enforced. Missing docstrings are ignored.

Minor commenting quirks of the code base are adapted.

Signed-off-by: Bobby Noelte <[email protected]>

* Improve Markdown handling and switch to Markdown documentation.

Switch to Markdown for the documentation files to improve the user and developer experience (see issue #181).

Keep files with special directives for automatic API documentation in RST format. The
directives expect RST.

Also add dummy handling for openai/ swagger server documentation. The openai interface definition is
for now taken from the fastapi PR as EOS will switch to fastAPI.

Signed-off-by: Bobby Noelte <[email protected]>

---------

Signed-off-by: Bobby Noelte <[email protected]>
Co-authored-by: Normann <[email protected]>

.gitignore

@@ -67,6 +67,9 @@ coverage.xml
 .pytest_cache/
 cover/
 
+# Documentation generation
+_autosummary/
+
 # Translations
 *.mo
 *.pot

Makefile

@@ -1,5 +1,5 @@
 # Define the targets
-.PHONY: help venv pip install dist test test-full docker-run docs clean
+.PHONY: help venv pip install dist test test-full docker-run docs read-docs clean
 
 # Default target
 all: help
@@ -14,6 +14,7 @@ help:
 	@echo "  docker-run   - Run entire setup on docker"
 	@echo "  docker-build - Rebuild docker image"
 	@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."
@@ -51,11 +52,18 @@ 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"
-	rm -rf dist
-	rm -rf .venv
+	@echo "Cleaning virtual env, distribution and build directories"
+	rm -rf dist build .venv
+	@echo "Searching and deleting all '_autosum' directories in docs..."
+	@find docs -type d -name '_autosummary' -exec rm -rf {} +;
+	@echo "Deletion complete."
 
 run:
 	@echo "Starting flask server, please wait..."

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 %}

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 %}

docs/akkudoktoreos/about.rst → docs/akkudoktoreos/about.md

@@ -1,11 +1,6 @@
-..
-    Copyright (c) 2024 Bobby Noelte
-    SPDX-License-Identifier: Apache-2.0
+% SPDX-License-Identifier: Apache-2.0
 
-.. _akkudoktoreos_about:
-
-About Akkudoktor EOS
-####################
+# About Akkudoktor EOS
 
 The Energy System Simulation and Optimization System (EOS) provides a comprehensive solution for
 simulating and optimizing an energy system based on renewable energy sources. With a focus on

docs/akkudoktoreos/api.rst

@@ -0,0 +1,16 @@
+..
+    SPDX-License-Identifier: Apache-2.0
+    File has to be of RST format to make autosummary directive work correctly
+
+.. _akkudoktoreos_api:
+
+EOS API
+=======
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: autosummary/module.rst
+   :recursive:
+
+   akkudoktoreos
+   akkudoktoreosserver