Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2025-09-13 07:21:16 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Add API documentation generation and use Markdown (#160)

Browse Source 
* 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 <b0661n0e17e@gmail.com>

* Enable Google style source commenting and documentation generation.

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

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* 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 <b0661n0e17e@gmail.com>

* 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 <b0661n0e17e@gmail.com>

---------

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: Normann <github@koldrack.com>
This commit is contained in:
Bobby Noelte
2024-11-10 23:27:52 +01:00
committed by GitHub
parent 3652298134
commit 94467e1a69
28 changed files with 1287 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
Makefile
View File

@@ -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..."