chore: improve doc generation and test (#762)

Improve documentation generation and add tests for documentation.
Extend sphinx by todo directive.

The configuration table is now split into several tables. The test
is adapted accordingly.

There is a new test that checks the docstrings to be compliant to the
RST format as used by sphinx to create the documentation. We can not
use Markdown in docstrings. The docstrings are adapted accordingly.

An additional test checks that the documentation can be build with sphinx.
This test takes very long is only enabled in full run (aka. ci) mode.

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

scripts/generate_openapi_md.py

@@ -194,6 +194,8 @@ def format_endpoint(path: str, method: str, details: dict, devel: bool = False)
 
     markdown = f"## {method.upper()} {path}\n\n"
 
+    # -- links
+    markdown += "<!-- pyml disable line-length -->\n"
     markdown += f"**Links**: {local_path}, {akkudoktoreos_main_path}"
     if devel:
         # Add link to akkudoktor branch the development has used
@@ -206,7 +208,8 @@ def format_endpoint(path: str, method: str, details: dict, devel: bool = False)
                 + link_method
             )
             markdown += f", {akkudoktoreos_base_path}"
-    markdown += "\n\n"
+    markdown += "\n<!-- pyml enable line-length -->\n\n"
+    # -- links end
 
     summary = details.get("summary", None)
     if summary:
@@ -214,9 +217,14 @@ def format_endpoint(path: str, method: str, details: dict, devel: bool = False)
 
     description = details.get("description", None)
     if description:
-        markdown += "```\n"
-        markdown += f"{description}"
-        markdown += "\n```\n\n"
+        # -- code block
+        markdown += "<!-- pyml disable line-length -->\n"
+        markdown += "```python\n"
+        markdown += '"""\n'
+        markdown += f"{description}\n"
+        markdown += '"""\n'
+        markdown += "```\n<!-- pyml enable line-length -->\n\n"
+        # -- end code block end
 
     markdown += format_parameters(details.get("parameters", []))
     markdown += format_request_body(details.get("requestBody", {}).get("content", {}))
@@ -239,7 +247,11 @@ def openapi_to_markdown(openapi_json: dict, devel: bool = False) -> str:
     info = extract_info(openapi_json)
     markdown = f"# {info['title']}\n\n"
     markdown += f"**Version**: `{info['version']}`\n\n"
-    markdown += f"**Description**: {info['description']}\n\n"
+    # -- description
+    markdown += "<!-- pyml disable line-length -->\n"
+    markdown += f"**Description**: {info['description']}\n"
+    markdown += "<!-- pyml enable line-length -->\n\n"
+    # -- end description
     markdown += f"**Base URL**: `{info['base_url']}`\n\n"
 
     security_schemes = openapi_json.get("components", {}).get("securitySchemes", {})
@@ -257,6 +269,8 @@ def openapi_to_markdown(openapi_json: dict, devel: bool = False) -> str:
     markdown = markdown.rstrip("\n")
     markdown += "\n"
 
+    markdown += "\nAuto generated from openapi.json.\n"
+
     return markdown