Collect functions used for documentation building in docs_utils.py (#…

…1380) * Collect functions used for documentation building in `docs_utils.py` * Update documentation and fix bug * Move more functions into `docs_utils.py`
XENONnT · May 16, 2024 · 465e596 · 465e596
1 parent 6effa1e
commit 465e596
Show file tree

Hide file tree

Showing 15 changed files with 209 additions and 101 deletions.
diff --git a/docs/source/build_datastructure_doc.py b/docs/source/build_datastructure_doc.py
@@ -18,6 +18,7 @@
 import strax
 import straxen
 from straxen import kind_colors
+from straxen.docs_utils import add_spaces, add_deps_to_graph_tree
 
 this_dir = os.path.dirname(os.path.realpath(__file__))
 
@@ -121,20 +122,6 @@
         kind_colors[c + suffix] = kind_colors[c]
 
 
-def add_spaces(x):
-    """Add four spaces to every line in x.
-
-    This is needed to make html raw blocks in rst format correctly
-
-    """
-    y = ""
-    if isinstance(x, str):
-        x = x.split("\n")
-    for q in x:
-        y += "    " + q
-    return y
-
-
 def get_plugins_deps(st):
     """For a given Strax.Context return the dependencies per plugin split by the known
     tree_suffices.
@@ -246,30 +233,6 @@ def build_datastructure_doc(is_nt):
         shutil.rmtree(this_dir + f"/graphs{suffix}_{one_tonne_or_n_tonne}")
 
 
-def add_deps_to_graph_tree(graph_tree, plugin, data_type, _seen=None):
-    """Recursively add nodes to graph base on plugin.deps."""
-    if _seen is None:
-        _seen = []
-    if data_type in _seen:
-        return graph_tree, _seen
-
-    # Add new one
-    graph_tree.node(
-        data_type,
-        style="filled",
-        href="#" + data_type.replace("_", "-"),
-        fillcolor=kind_colors.get(plugin.data_kind_for(data_type), "grey"),
-    )
-    for dep in plugin.depends_on:
-        graph_tree.edge(data_type, dep)
-
-    # Add any of the lower plugins if we have to
-    for lower_data_type, lower_plugin in plugin.deps.items():
-        graph_tree, _seen = add_deps_to_graph_tree(graph_tree, lower_plugin, lower_data_type, _seen)
-    _seen.append(data_type)
-    return graph_tree, _seen
-
-
 def tree_to_svg(graph_tree, save_as="data_kinds_nT"):
     # Where to save this node
     graph_tree.render(save_as)

diff --git a/docs/source/build_release_notes.py b/docs/source/build_release_notes.py
@@ -1,43 +1,10 @@
-from m2r import convert
 import os
+from straxen.docs_utils import convert_release_notes
 
-header = """
-Release notes
-==============
 
-"""
-
-
-def convert_release_notes():
-    """Convert the release notes to an RST page with links to PRs."""
+if __name__ == "__main__":
     this_dir = os.path.dirname(os.path.realpath(__file__))
     notes = os.path.join(this_dir, "..", "..", "HISTORY.md")
-    with open(notes, "r") as f:
-        notes = f.read()
-    rst = convert(notes)
-    with_ref = ""
-    for line in rst.split("\n"):
-        # Get URL for PR
-        if "#" in line:
-            pr_number = line.split("#")[1]
-            while len(pr_number):
-                try:
-                    pr_number = int(pr_number)
-                    break
-                except ValueError:
-                    # Too many tailing characters to be an int
-                    pr_number = pr_number[:-1]
-            if pr_number:
-                line = line.replace(
-                    f"#{pr_number}",
-                    f"`#{pr_number} <https://github.com/XENONnT/straxen/pull/{pr_number}>`_",
-                )
-        with_ref += line + "\n"
     target = os.path.join(this_dir, "reference", "release_notes.rst")
-
-    with open(target, "w") as f:
-        f.write(header + with_ref)
-
-
-if __name__ == "__main__":
-    convert_release_notes()
+    pull_url = "https://github.com/XENONnT/straxen/pull"
+    convert_release_notes(notes, target, pull_url)
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -204,4 +204,9 @@ def setup(app):
     build_context_doc.main()
     from build_release_notes import convert_release_notes
 
-    convert_release_notes()
+    this_dir = os.path.dirname(os.path.realpath(__file__))
+    notes = os.path.join(this_dir, "..", "..", "HISTORY.md")
+    target = os.path.join(this_dir, "reference", "release_notes.rst")
+    pull_url = "https://github.com/XENONnT/straxen/pull"
+
+    convert_release_notes(notes, target, pull_url)
diff --git a/docs/source/reference/straxen.legacy.plugins_1t.rst b/docs/source/reference/straxen.legacy.plugins_1t.rst
@@ -12,6 +12,14 @@ straxen.legacy.plugins\_1t.event\_info module
    :undoc-members:
    :show-inheritance:
 
+straxen.legacy.plugins\_1t.fake\_daqreader module
+-------------------------------------------------
+
+.. automodule:: straxen.legacy.plugins_1t.fake_daqreader
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.legacy.plugins\_1t.pax\_interface module
 ------------------------------------------------
 

diff --git a/docs/source/reference/straxen.plugins.detector_time_offsets.rst b/docs/source/reference/straxen.plugins.detector_time_offsets.rst
diff --git a/docs/source/reference/straxen.plugins.events.rst b/docs/source/reference/straxen.plugins.events.rst
@@ -52,6 +52,14 @@ straxen.plugins.events.event\_basics module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.events.event\_basics\_som module
+------------------------------------------------
+
+.. automodule:: straxen.plugins.events.event_basics_som
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.events.event\_info module
 -----------------------------------------
 
@@ -68,6 +76,14 @@ straxen.plugins.events.event\_info\_double module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.events.event\_nearest\_triggering module
+--------------------------------------------------------
+
+.. automodule:: straxen.plugins.events.event_nearest_triggering
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.events.event\_pattern\_fit module
 -------------------------------------------------
 
@@ -116,6 +132,14 @@ straxen.plugins.events.event\_s2\_positions\_mlp module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.events.event\_se\_sensity module
+------------------------------------------------
+
+.. automodule:: straxen.plugins.events.event_se_sensity
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.events.event\_shadow module
 -------------------------------------------
 

diff --git a/docs/source/reference/straxen.plugins.gps_syncing.rst b/docs/source/reference/straxen.plugins.gps_syncing.rst
@@ -0,0 +1,21 @@
+straxen.plugins.gps\_syncing package
+====================================
+
+Submodules
+----------
+
+straxen.plugins.gps\_syncing.gps\_syncing module
+------------------------------------------------
+
+.. automodule:: straxen.plugins.gps_syncing.gps_syncing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: straxen.plugins.gps_syncing
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/straxen.plugins.peaklets.rst b/docs/source/reference/straxen.plugins.peaklets.rst
@@ -12,6 +12,14 @@ straxen.plugins.peaklets.peaklet\_classification module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.peaklets.peaklet\_classification\_som module
+------------------------------------------------------------
+
+.. automodule:: straxen.plugins.peaklets.peaklet_classification_som
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.peaklets.peaklets module
 ----------------------------------------
 

diff --git a/docs/source/reference/straxen.plugins.peaks.rst b/docs/source/reference/straxen.plugins.peaks.rst
@@ -20,6 +20,14 @@ straxen.plugins.peaks.peak\_basics module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.peaks.peak\_basics\_som module
+----------------------------------------------
+
+.. automodule:: straxen.plugins.peaks.peak_basics_som
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.peaks.peak\_classification\_bayes module
 --------------------------------------------------------
 
@@ -36,6 +44,14 @@ straxen.plugins.peaks.peak\_corrections module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.peaks.peak\_nearest\_triggering module
+------------------------------------------------------
+
+.. automodule:: straxen.plugins.peaks.peak_nearest_triggering
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.peaks.peak\_per\_event module
 ---------------------------------------------
 
@@ -92,6 +108,14 @@ straxen.plugins.peaks.peak\_s1\_positions\_cnn module
    :undoc-members:
    :show-inheritance:
 
+straxen.plugins.peaks.peak\_se\_sensity module
+----------------------------------------------
+
+.. automodule:: straxen.plugins.peaks.peak_se_sensity
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.plugins.peaks.peak\_shadow module
 -----------------------------------------
 
@@ -116,10 +140,10 @@ straxen.plugins.peaks.peaks module
    :undoc-members:
    :show-inheritance:
 
-straxen.plugins.peaks.peaks\_subtyping module
----------------------------------------------
+straxen.plugins.peaks.peaks\_som module
+---------------------------------------
 
-.. automodule:: straxen.plugins.peaks.peaks_subtyping
+.. automodule:: straxen.plugins.peaks.peaks_som
    :members:
    :undoc-members:
    :show-inheritance:

diff --git a/docs/source/reference/straxen.plugins.ref_mon_nv.rst b/docs/source/reference/straxen.plugins.ref_mon_nv.rst
@@ -0,0 +1,21 @@
+straxen.plugins.ref\_mon\_nv package
+====================================
+
+Submodules
+----------
+
+straxen.plugins.ref\_mon\_nv.ref\_mon\_nv module
+------------------------------------------------
+
+.. automodule:: straxen.plugins.ref_mon_nv.ref_mon_nv
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: straxen.plugins.ref_mon_nv
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/reference/straxen.plugins.rst b/docs/source/reference/straxen.plugins.rst
@@ -9,10 +9,10 @@ Subpackages
 
    straxen.plugins.afterpulses
    straxen.plugins.aqmon_hits
-   straxen.plugins.detector_time_offsets
    straxen.plugins.events
    straxen.plugins.events_mv
    straxen.plugins.events_nv
+   straxen.plugins.gps_syncing
    straxen.plugins.hitlets_mv
    straxen.plugins.hitlets_nv
    straxen.plugins.individual_peak_monitor
@@ -32,6 +32,7 @@ Subpackages
    straxen.plugins.records_he
    straxen.plugins.records_mv
    straxen.plugins.records_nv
+   straxen.plugins.ref_mon_nv
    straxen.plugins.veto_intervals
 
 Submodules

diff --git a/docs/source/reference/straxen.rst b/docs/source/reference/straxen.rst
@@ -56,6 +56,14 @@ straxen.daq\_core module
    :undoc-members:
    :show-inheritance:
 
+straxen.docs\_utils module
+--------------------------
+
+.. automodule:: straxen.docs_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 straxen.entry\_points module
 ----------------------------
 

diff --git a/requirements.txt b/requirements.txt
@@ -11,6 +11,7 @@ multihist>=0.6.3
 numba>=0.50.0
 numpy
 packaging
+m2r
 pymongo
 requests
 strax>=1.5.0

diff --git a/straxen/__init__.py b/straxen/__init__.py
@@ -35,6 +35,9 @@
 from . import test_utils
 from .test_utils import *
 
+from . import docs_utils
+from .docs_utils import *
+
 from . import daq_core
 
 try: