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

docs/conf.py

@@ -1,14 +1,12 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Configuration file for the Sphinx documentation builder.
+
+For the full list of built-in configuration values, see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
 
 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
 
@@ -23,7 +21,9 @@ release = "0.0.1"
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
+    "sphinxcontrib.openapi",
     "myst_parser",
 ]
 
@@ -36,6 +36,59 @@ source_suffix = {
     ".md": "markdown",
 }
 
+# -- Options for Myst Markdown -----------------------------------------------
+# see https://github.com/executablebooks/MyST-Parser/blob/master/docs/conf.py
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "colon_fence",
+    "smartquotes",
+    "replacements",
+    "linkify",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+    "attrs_inline",
+    "attrs_block",
+]
+myst_url_schemes = {
+    "http": None,
+    "https": None,
+    "mailto": None,
+    "ftp": None,
+    "wiki": "https://en.wikipedia.org/wiki/{{path}}#{{fragment}}",
+    "doi": "https://doi.org/{{path}}",
+    "gh-pr": {
+        "url": "https://github.com/Akkudoktor-EOS/EOS/pull/{{path}}#{{fragment}}",
+        "title": "PR #{{path}}",
+        "classes": ["github"],
+    },
+    "gh-issue": {
+        "url": "https://github.com/Akkudoktor-EOS/EOS/issue/{{path}}#{{fragment}}",
+        "title": "Issue #{{path}}",
+        "classes": ["github"],
+    },
+    "gh-user": {
+        "url": "https://github.com/{{path}}",
+        "title": "@{{path}}",
+        "classes": ["github"],
+    },
+}
+myst_number_code_blocks = ["typescript"]
+myst_heading_anchors = 2
+myst_footnote_transition = True
+myst_dmath_double_inline = True
+myst_enable_checkboxes = True
+myst_substitutions = {
+    "role": "[role](#syntax/roles)",
+    "directive": "[directive](#syntax/directives)",
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -46,3 +99,39 @@ html_theme_options = {
     "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
+
+# -- Options for openapi -----------------------------------------------------
+openapi_default_renderer = "httpdomain:old"
+
+# -- Options for napoleon -------------------------------------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True