Remove troubleshooting pages and fix code documentation generation

docs/gen_ref_pages.py

@@ -5,40 +5,33 @@ from pathlib import Path
 
 import mkdocs_gen_files
 
-nav = mkdocs_gen_files.Nav()
-for directory in ["src"]:
-    for path in sorted(Path(directory).rglob("*.py")):
-
-        module_path = path.relative_to(directory).with_suffix("")
+src = Path(__file__).parent.parent / "src"
 
-        doc_path = path.relative_to(directory).with_suffix(".md")
-
-        full_doc_path = Path("reference", doc_path)
+nav = mkdocs_gen_files.Nav()
 
-        parts = list(module_path.parts)
+for path in sorted(src.rglob("*.py")):
 
-        if parts[-1] in [
-            "notebooks", "settings",
-            "restful_config", "__main__",
-            "__init__", "listen_kafka",
-            "sqlite_view", "manual_launch"
-            "messages",
-        ]:
-            continue
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+    parts = list(module_path.parts)
 
-        nav[parts] = doc_path.as_posix() 
+    if parts[-1] in [
+        "notebooks", "settings",
+        "restful_config", "__main__",
+        "__init__", "listen_kafka",
+        "sqlite_view", "manual_launch"
+        "messages",
+    ]:
+        continue
 
-        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+    nav[parts] = doc_path.as_posix() 
 
-            identifier = ".".join(parts)
-            if "calcat_interface" == full_doc_path.stem:
-                # adding an note and image for calcat_interface.py
-                print("""??? Note "This module help in skipping calibrationDBRemote"\n\t[Calibration DB Remote avoided](xfel-calibrate_cli_process_no_caldbremote.png)
-                      """,
-                    file=fd)
-            print("::: " + "src." + identifier, file=fd)
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
 
-        mkdocs_gen_files.set_edit_path(full_doc_path, path)
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
 
 with mkdocs_gen_files.open(f"reference/SUMMARY.md", "w") as nav_file:
     nav_file.writelines(nav.build_literate_nav())

docs/operation/troubleshooting_calibration_generation.md

-# Troubleshooting Calibration constants generation
\ No newline at end of file

docs/operation/troubleshooting_correction.md

-# Troubleshooting correction
\ No newline at end of file

mkdocs.yml

@@ -65,20 +65,20 @@ plugins:
   - glightbox
   - search
   - autorefs
-  # - gen-files:
-  #     scripts:
-  #       - docs/gen_ref_pages.py
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
   - literate-nav:
       nav_file: SUMMARY.md
   - section-index
-  # - mkdocstrings:
-  #     handlers:
-  #       python:
-  #         import:
-  #         - https://docs.python-requests.org/en/master/objects.inv
-  #         paths: [src]
-  #         docstring_style: "sphinx"
-  #         docstring_section_style: "list"
+  - mkdocstrings:
+      handlers:
+        python:
+          import:
+          - https://docs.python-requests.org/en/master/objects.inv
+          # paths: [src/cal_tools]
+          docstring_style: "sphinx"
+          docstring_section_style: "list"
 
 repo_url: https://git.xfel.eu/calibration/pycalibration
 
@@ -92,9 +92,6 @@ nav:
       - Calibration webservice:
         - The webservice: operation/webservice.md
         - Calibration Configuration: operation/calibration_configurations.md
-      - Troubleshooting:
-        - Correcting detector RAW data: operation/troubleshooting_correction.md
-        - Calibration constant generation: operation/troubleshooting_calibration_generation.md
     - Development:
       - Installation: development/installation.md
       - Workflow: development/workflow.md