Documentation (#148)

* Streamline Sphinx conf * Avoid Sphinx from being too nitpicky * Fix docstrings * Suppress warning about missing appearance in toctree for API * Declare api.rst as orphan, i.e. Sphinx should not complain that it is not included in any toctree * Fix unimportable gainMakers class * Fix import * Fix link to other doc pages * Fix sub-module imports both in script and API, and both using relative (in API) and absolute (in scripts) imports. * Play with Numpydoc options * Fix import to ctapipe containers in Franca's tools * Scriptify DQM * Exclude DQM Bokeh app from doc (can't be easily scriptified without embedding the Tornado server) from Sphinx doc build, as well as Franca's tools (which are very outdated). * Update ctapipe traitlets calls in Franca's tools * Playing with suppress_warnings in Sphinx configuration * Use mock imports instead of suppressing warnings. --------- Co-authored-by: Jean-Philippe Lenain <jlenain@in2p3.fr>
cta-observatory · Aug 22, 2024 · b4a2ef7 · b4a2ef7
1 parent 7554a70
commit b4a2ef7
Show file tree

Hide file tree

Showing 20 changed files with 367 additions and 322 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -W --keep-going -n --color -j auto
+SPHINXOPTS    ?= -W --keep-going --color -j auto
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

diff --git a/docs/api.rst b/docs/api.rst
@@ -4,6 +4,8 @@
    (not declared in any toctree) to remove an unnecessary intermediate page; index.rst instead points directly to the
    package page. DO NOT REMOVE THIS FILE!
 
+:orphan:
+
 .. autosummary::
    :toctree: _autosummary
    :template: custom-module-template.rst

diff --git a/docs/conf.py b/docs/conf.py
@@ -64,22 +64,31 @@
 # autodoc_typehints = "description" # Sphinx-native method. Not as good as
 # sphinx_autodoc_typehints
 add_module_names = False  # Remove namespaces from class/method signatures
+numpydoc_show_class_members = False
+numpydoc_show_inherited_class_members = False
+# cf. https://stackoverflow.com/a/73294408:
+numpydoc_class_members_toctree = False
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
-# The master toctree document.
-master_doc = "index"
-
-# have all links automatically associated with the right domain.
-default_role = "py:obj"
-
 templates_path = ["_templates"]
 
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "**/*.dqm.bokeh_app**",
+]
+
+autodoc_mock_imports = [
+    "nectarchain.makers.extractor.charge_extractor",
+    "nectarchain.makers.calibration.core",
+    "nectarchain.dqm.bokeh_app",
+]
 
 # intersphinx allows referencing other packages sphinx docs
 intersphinx_mapping = {
@@ -92,27 +101,10 @@
     "ctapipe": ("https://ctapipe.readthedocs.io/en/v0.19.3/", None),
 }
 
-# These links are ignored in the checks, necessary due to broken intersphinx for these
-nitpick_ignore = [
-    ("py:obj", "enum.auto"),
-    ("py:obj", "enum.IntFlag"),
-    ("py:obj", "enum.unique"),
-    # coming from inherited traitlets docs
-    ("py:class", "t.Union"),
-    ("py:class", "t.Dict"),
-    ("py:class", "t.Tuple"),
-    ("py:class", "t.List"),
-    ("py:class", "t.Any"),
-    ("py:class", "t.Type"),
-    ("py:class", "Config"),
-    ("py:class", "Unicode"),
-    ("py:class", "StrDict"),
-    ("py:class", "ClassesType"),
-]
-
-suppress_warnings = [
-    "autosummary",
-]
+# suppress_warnings = [
+#     "autosummary",
+#     "autosummary.import_cycle",
+# ]
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
@@ -143,6 +135,7 @@
 
 html_theme = "pydata_sphinx_theme"
 # html_theme = "alabaster"
+# html_theme = "sphinx_rtd_theme"
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = f"{project}doc"

diff --git a/docs/user-guide/troubleshooting.rst b/docs/user-guide/troubleshooting.rst
@@ -3,22 +3,22 @@
 Troubleshooting
 ===============
 
-.. _note_mac_users
+.. _note_mac_users:
 
 Note to macOS users
 -------------------
 
 macOS users may experience errors when trying to initialize a proxy to DIRAC when the
-`DIRAC support <optional-dirac-support>`_ is enabled, especially with recent
+DIRAC support is enabled (see :ref:`optional-dirac-support`), especially with recent
 hardware equipped with M1 or M2 Apple CPU chips. Two possible workarounds are proposed
 below.
 
-Downgrading `voms`
-^^^^^^^^^^^^^^^^^^
+Downgrading ``voms``
+^^^^^^^^^^^^^^^^^^^^
 
 Some Mac OS users (running on M1 or M2 chips) may experience a ``M2Crypto.SSL.SSLError``
 error when trying to initiate a DIRAC proxy with ``dirac-proxy-init``. During the
-`installation process <optional-dirac-support>`_, instead of:
+installation process (see :ref:`optional-dirac-support`), instead of:
 
 .. code-block:: console
 

diff --git a/src/nectarchain/data/management.py b/src/nectarchain/data/management.py
@@ -44,7 +44,7 @@ def findrun(run_number: int, search_on_GRID=True) -> Tuple[Path, List[Path]]:
         Returns
         -------
         (PosixPath,list):
-            the path list of `*fits.fz` files
+            the path list of ``*.fits.fz`` files
 
         """
         basepath = f"{os.environ['NECTARCAMDATA']}/runs/"

diff --git a/src/nectarchain/dqm/__init__.py b/src/nectarchain/dqm/__init__.py
@@ -1,5 +1,23 @@
-from .db_utils import DQMDB
+"""
+Module for Data Quality Monitoring
+"""
+
+from .camera_monitoring import CameraMonitoring
+from .charge_integration import ChargeIntegrationHighLowGain
 from .dqm_summary_processor import DQMSummary
+from .mean_camera_display import MeanCameraDisplayHighLowGain
+from .mean_waveforms import MeanWaveFormsHighLowGain
 from .pixel_participation import PixelParticipationHighLowGain
+from .pixel_timeline import PixelTimelineHighLowGain
+from .trigger_statistics import TriggerStatistics
 
-__all__ = ["DQMDB", "DQMSummary", "PixelParticipationHighLowGain"]
+__all__ = [
+    "CameraMonitoring",
+    "ChargeIntegrationHighLowGain",
+    "DQMSummary",
+    "MeanCameraDisplayHighLowGain",
+    "MeanWaveFormsHighLowGain",
+    "PixelParticipationHighLowGain",
+    "PixelTimelineHighLowGain",
+    "TriggerStatistics",
+]
diff --git a/src/nectarchain/dqm/bokeh_app/main.py b/src/nectarchain/dqm/bokeh_app/main.py
@@ -1,18 +1,19 @@
 import numpy as np
-from app_hooks import get_rundata, make_camera_displays
 
 # bokeh imports
 from bokeh.layouts import layout, row
 from bokeh.models import Select  # , NumericInput
 from bokeh.plotting import curdoc
-from ctapipe.coordinates import EngineeringCameraFrame
 
 # ctapipe imports
+from ctapipe.coordinates import EngineeringCameraFrame
 from ctapipe.instrument import CameraGeometry
 from ctapipe_io_nectarcam import constants
 
 from nectarchain.dqm.db_utils import DQMDB
 
+from .app_hooks import get_rundata, make_camera_displays
+
 NOTINDISPLAY = [
     "Results_TriggerStatistics",
     "Results_MeanWaveForms_HighGain",

diff --git a/src/nectarchain/dqm/camera_monitoring.py b/src/nectarchain/dqm/camera_monitoring.py
@@ -7,7 +7,9 @@
 from ctapipe.visualization import CameraDisplay
 from matplotlib import pyplot as plt
 
-from nectarchain.dqm.dqm_summary_processor import DQMSummary
+from .dqm_summary_processor import DQMSummary
+
+__all__ = ["CameraMonitoring"]
 
 
 class CameraMonitoring(DQMSummary):

diff --git a/src/nectarchain/dqm/charge_integration.py b/src/nectarchain/dqm/charge_integration.py
@@ -6,7 +6,9 @@
 from matplotlib import pyplot as plt
 from traitlets.config.loader import Config
 
-from nectarchain.dqm.dqm_summary_processor import DQMSummary
+from .dqm_summary_processor import DQMSummary
+
+__all__ = ["ChargeIntegrationHighLowGain"]
 
 
 class ChargeIntegrationHighLowGain(DQMSummary):

diff --git a/src/nectarchain/dqm/mean_camera_display.py b/src/nectarchain/dqm/mean_camera_display.py
@@ -3,7 +3,9 @@
 from ctapipe.visualization import CameraDisplay
 from matplotlib import pyplot as plt
 
-from nectarchain.dqm.dqm_summary_processor import DQMSummary
+from .dqm_summary_processor import DQMSummary
+
+__all__ = ["MeanCameraDisplayHighLowGain"]
 
 
 class MeanCameraDisplayHighLowGain(DQMSummary):

diff --git a/src/nectarchain/dqm/mean_waveforms.py b/src/nectarchain/dqm/mean_waveforms.py
@@ -1,7 +1,9 @@
 import numpy as np
 from matplotlib import pyplot as plt
 
-from nectarchain.dqm.dqm_summary_processor import DQMSummary
+from .dqm_summary_processor import DQMSummary
+
+__all__ = ["MeanWaveFormsHighLowGain"]
 
 
 class MeanWaveFormsHighLowGain(DQMSummary):

diff --git a/src/nectarchain/dqm/pixel_participation.py b/src/nectarchain/dqm/pixel_participation.py
@@ -3,7 +3,7 @@
 from ctapipe.visualization import CameraDisplay
 from matplotlib import pyplot as plt
 
-from nectarchain.dqm.dqm_summary_processor import DQMSummary
+from .dqm_summary_processor import DQMSummary
 
 __all__ = ["PixelParticipationHighLowGain"]
 

diff --git a/src/nectarchain/dqm/pixel_timeline.py b/src/nectarchain/dqm/pixel_timeline.py
@@ -1,7 +1,9 @@
 import numpy as np
 from matplotlib import pyplot as plt
 
-from nectarchain.dqm.dqm_summary_processor import DQMSummary
+from .dqm_summary_processor import DQMSummary
+
+__all__ = ["PixelTimelineHighLowGain"]
 
 
 class PixelTimelineHighLowGain(DQMSummary):