Use straxen documentation building functions to avoid duplicated codes (

#218)

* Fix bug when building docs locally

* Use straxen documentation building functions to avoid duplicated codes

* Move colors of data_kind into common.py

* Update requirements

docs/source/build_plugin_pages.py

@@ -1,31 +1,20 @@
 # Script to automatically generate the documentation pages for the plugins
 import fuse
+from straxen import kind_colors
 import os
 import graphviz
 import shutil
+from straxen.docs_utils import add_spaces, add_deps_to_graph_tree
 
-kind_colors = dict(
-    geant4_interactions="#40C4F3",
-    clustered_interactions="#FBCE56",
-    tpc_interactions="#F44E43",
-    below_cathode_interactions="#F44E43",
-    interactions_in_roi="#56C46C",
-    s1_photons="#54E4CF",
-    s2_photons="#54E4CF",
-    ap_photons="#54E4CF",
-    propagated_photons="#54E4CF",
-    pulse_ids="#54E4CF",
-    pulse_windows="#F78C27",
-    raw_records="#0260EF",
-    individual_electrons="#F44E43",
-)
+kind_colors.update(fuse.common.kind_colors)
 
 # List of config options that are not tracked
 config_options_not_tracked = [
     "debug",
     "raw_records_file_size_target",
     "min_records_gap_length_for_splitting",
-    "input_file" "path",
+    "input_file",
+    "path",
     "file_name",
     "propagated_s2_photons_file_size_target",
     "min_electron_gap_length_for_splitting",
@@ -124,43 +113,6 @@ def reformat_docstring(docstring):
     return y
 
 
-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 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 create_plugin_documentation_text(st, plugin):
 
     output = ""

docs/source/build_release_notes.py

@@ -1,48 +1,10 @@
-# Copied from straxen/docs/source/build_release_notes.py
-# https://github.com/XENONnT/straxen/blob/a34a02393001f13755c3f84d15924f83bc86c4db
-# /docs/source/build_release_notes.py
-
 import os
+from straxen.docs_utils import convert_release_notes
 
-from m2r import convert
-
-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/fuse/pull/{pr_number}>`_",
-                )
-        with_ref += line + "\n"
     target = os.path.join(this_dir, "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/fuse/pull"
+    convert_release_notes(notes, target, pull_url)

docs/source/conf.py

@@ -52,5 +52,10 @@ def setup(app):
     from build_release_notes import convert_release_notes
     from build_plugin_pages import build_all_pages
 
-    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, "release_notes.rst")
+    pull_url = "https://github.com/XENONnT/fuse/pull"
+
+    convert_release_notes(notes, target, pull_url)
     build_all_pages()

fuse/common.py

@@ -8,6 +8,23 @@
 FUSE_PLUGIN_TIMEOUT = 600
 
 
+kind_colors = dict(
+    geant4_interactions="#40C4F3",
+    clustered_interactions="#FBCE56",
+    tpc_interactions="#F44E43",
+    below_cathode_interactions="#F44E43",
+    interactions_in_roi="#56C46C",
+    s1_photons="#54E4CF",
+    s2_photons="#54E4CF",
+    ap_photons="#54E4CF",
+    propagated_photons="#54E4CF",
+    pulse_ids="#54E4CF",
+    pulse_windows="#F78C27",
+    raw_records="#0260EF",
+    individual_electrons="#F44E43",
+)
+
+
 @numba.njit()
 def dynamic_chunking(data, scale, n_min):
     idx_sort = np.argsort(data)

pyproject.toml

@@ -37,7 +37,7 @@ numba = ">=0.58.1"
 awkward = ">=2.5.1"
 uproot = ">=5.2.1"
 strax = ">=1.6.0"
-straxen = ">=2.2.0"
+straxen = ">=2.2.3"
 
 [build-system]
 requires = ["poetry-core>=1.0.8", "setuptools"]