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>

tests/test_doc.py

@@ -1,5 +1,6 @@
 import json
 import os
+import shutil
 import sys
 from pathlib import Path
 from unittest.mock import patch
@@ -9,6 +10,9 @@ import pytest
 DIR_PROJECT_ROOT = Path(__file__).parent.parent
 DIR_TESTDATA = Path(__file__).parent / "testdata"
 
+DIR_DOCS_GENERATED = DIR_PROJECT_ROOT / "docs" / "_generated"
+DIR_TEST_GENERATED = DIR_TESTDATA / "docs" / "_generated"
+
 
 def test_openapi_spec_current(config_eos):
     """Verify the openapi spec hasn´t changed."""
@@ -74,11 +78,14 @@ def test_openapi_md_current(config_eos):
 
 def test_config_md_current(config_eos):
     """Verify the generated configuration markdown hasn´t changed."""
-    expected_config_md_path = DIR_PROJECT_ROOT / "docs" / "_generated" / "config.md"
-    new_config_md_path = DIR_TESTDATA / "config-new.md"
+    assert DIR_DOCS_GENERATED.exists()
 
-    with expected_config_md_path.open("r", encoding="utf-8", newline=None) as f_expected:
-        expected_config_md = f_expected.read()
+    # Remove any leftover files from last run
+    if DIR_TEST_GENERATED.exists():
+        shutil.rmtree(DIR_TEST_GENERATED)
+
+    # Ensure test dir exists
+    DIR_TEST_GENERATED.mkdir(parents=True, exist_ok=True)
 
     # Patch get_config and import within guard to patch global variables within the eos module.
     with patch("akkudoktoreos.config.config.get_config", return_value=config_eos):
@@ -87,17 +94,33 @@ def test_config_md_current(config_eos):
         sys.path.insert(0, str(root_dir))
         from scripts import generate_config_md
 
-        config_md = generate_config_md.generate_config_md(config_eos)
+        # Get all the top level fields
+        field_names = sorted(config_eos.__class__.model_fields.keys())
 
-    if os.name == "nt":
-        config_md = config_md.replace("\\\\", "/")
-    with new_config_md_path.open("w", encoding="utf-8", newline="\n") as f_new:
-        f_new.write(config_md)
+        # Create the file paths
+        expected = [ DIR_DOCS_GENERATED / "config.md", DIR_DOCS_GENERATED / "configexample.md", ]
+        tested = [ DIR_TEST_GENERATED / "config.md", DIR_TEST_GENERATED / "configexample.md", ]
+        for field_name in field_names:
+            file_name = f"config{field_name.lower()}.md"
+            expected.append(DIR_DOCS_GENERATED / file_name)
+            tested.append(DIR_TEST_GENERATED / file_name)
 
-    try:
-        assert config_md == expected_config_md
-    except AssertionError as e:
-        pytest.fail(
-            f"Expected {new_config_md_path} to equal {expected_config_md_path}.\n"
-            + f"If ok: `make gen-docs` or `cp {new_config_md_path} {expected_config_md_path}`\n"
-        )
+        # Create test files
+        config_md = generate_config_md.generate_config_md(tested[0], config_eos)
+
+    # Check test files are the same as the expected files
+    for i, expected_path in enumerate(expected):
+        tested_path = tested[i]
+
+        with expected_path.open("r", encoding="utf-8", newline=None) as f_expected:
+            expected_config_md = f_expected.read()
+        with tested_path.open("r", encoding="utf-8", newline=None) as f_expected:
+            tested_config_md = f_expected.read()
+
+        try:
+            assert tested_config_md == expected_config_md
+        except AssertionError as e:
+            pytest.fail(
+                f"Expected {tested_path} to equal {expected_path}.\n"
+                + f"If ok: `make gen-docs` or `cp {tested_path} {expected_path}`\n"
+            )