From 42d3733d4762078eb4307460fbf685720d37a818 Mon Sep 17 00:00:00 2001
From: Karim Ahmed <karim.ahmed@xfel.eu>
Date: Wed, 3 Jan 2024 10:18:58 +0100
Subject: [PATCH] Remove troubleshooting pages and fix code documentation
generation
---
docs/gen_ref_pages.py | 47 ++++++++-----------
.../troubleshooting_calibration_generation.md | 1 -
docs/operation/troubleshooting_correction.md | 1 -
mkdocs.yml | 25 +++++-----
src/__init__.py | 0
5 files changed, 31 insertions(+), 43 deletions(-)
delete mode 100644 docs/operation/troubleshooting_calibration_generation.md
delete mode 100644 docs/operation/troubleshooting_correction.md
create mode 100644 src/__init__.py
diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
index af1a47724..e840afd59 100644
--- a/docs/gen_ref_pages.py
+++ b/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())
diff --git a/docs/operation/troubleshooting_calibration_generation.md b/docs/operation/troubleshooting_calibration_generation.md
deleted file mode 100644
index b4e5c58c3..000000000
--- a/docs/operation/troubleshooting_calibration_generation.md
+++ /dev/null
@@ -1 +0,0 @@
-# Troubleshooting Calibration constants generation
\ No newline at end of file
diff --git a/docs/operation/troubleshooting_correction.md b/docs/operation/troubleshooting_correction.md
deleted file mode 100644
index 6d12aacb3..000000000
--- a/docs/operation/troubleshooting_correction.md
+++ /dev/null
@@ -1 +0,0 @@
-# Troubleshooting correction
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 697b683b8..080b5b97a 100644
--- a/mkdocs.yml
+++ b/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
diff --git a/src/__init__.py b/src/__init__.py
new file mode 100644
index 000000000..e69de29bb
--
GitLab