diff --git a/.gitignore b/.gitignore index 6d705e5b..6b64e762 100644 --- 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 index f3d04c8b..4f32818b 100644 --- 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 new file mode 100644 index 00000000..3cddd59e --- /dev/null +++ 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 new file mode 100644 index 00000000..be3cf987 --- /dev/null +++ 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 new file mode 100644 index 00000000..4a12825f --- /dev/null +++ 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 index 8d650608..b4928735 100644 --- 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 index 2986047a..4dbd642b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,3 +15,4 @@ Akkudoktor EOS documentation akkudoktoreos/about develop/getting_started develop/CONTRIBUTING + akkudoktoreos/api