Automatic documentation (#141)

* Use Sphinx auto type hints * Use recursive autosummary, to have even more automation for doc building * Follow configuration for recursive sphinx-autosummary from https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion * Adapt Sphinx makefile to clean _autosummary * Fix docstrings * Add custom templates for sphinx-autosummary, from https://github.com/JamesALeedham/Sphinx-Autosummary-Recursion * Add some inter-sphinx mappings * Don't inherit docstrings from base classes * The order of imported Sphinx extensions matters * Fix PEP-8 coding style * Fix external URL in doc * Logo for dark theme * Add PyPI and conda badges * Suppress warnings from sphinx.ext.autosummary --------- Co-authored-by: Jean-Philippe Lenain <[email protected]>
cta-observatory · Jul 31, 2024 · e4bef46 · e4bef46
1 parent 2efa03f
commit e4bef46
Show file tree

Hide file tree

Showing 26 changed files with 815 additions and 453 deletions.
diff --git a/.gitignore b/.gitignore
@@ -92,6 +92,7 @@ src/nectarchain/user_scripts/**/test
 **.log
 **.pdf
 **.csv
+**.png
 
 #VScode
 .vscode/

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# nectarchain [![Build Status](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml?query=workflow%3ACI+branch%3Amain)
+# nectarchain [![Build Status](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml?query=workflow%3ACI+branch%3Amain) [![pypi](https://badge.fury.io/py/nectarchain.svg)](https://badge.fury.io/py/nectarchain) [![conda](https://anaconda.org/conda-forge/nectarchain/badges/version.svg)](https://anaconda.org/conda-forge/nectarchain)
 
 Repository for the high level analysis of the NectarCAM data.
 The analysis is heavily based on [ctapipe](https://github.com/cta-observatory/ctapipe), adding custom code for NectarCAM calibration.

diff --git a/docs/Makefile b/docs/Makefile
@@ -20,5 +20,5 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:
-	rm -rf api
+	rm -rf _autosummary
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/nectarcam.png b/docs/_static/nectarcam.png
diff --git a/docs/_static/nectarcam_logo.webp b/docs/_static/nectarcam_logo.webp
diff --git a/docs/_static/nectarcam_logo_dark.webp b/docs/_static/nectarcam_logo_dark.webp
diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst
@@ -0,0 +1,33 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/api-reference/data/index.rst b/docs/api-reference/data/index.rst
diff --git a/docs/api-reference/display/index.rst b/docs/api-reference/display/index.rst
diff --git a/docs/api-reference/dqm/index.rst b/docs/api-reference/dqm/index.rst
diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst
diff --git a/docs/api-reference/tools/index.rst b/docs/api-reference/tools/index.rst
diff --git a/docs/api-reference/utils/index.rst b/docs/api-reference/utils/index.rst
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,12 @@
+..
+   DO NOT DELETE THIS FILE! It contains the all-important `.. autosummary::` directive with `:recursive:` option, without
+   which API documentation wouldn't get extracted from docstrings by the `sphinx.ext.autosummary` engine. It is hidden
+   (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!
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   nectarchain
diff --git a/docs/conf.py b/docs/conf.py
@@ -42,18 +42,25 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.githubpages",
-    "sphinx.ext.intersphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
-    "sphinx_automodapi.automodapi",
-    "sphinx_automodapi.smart_resolver",
-    "numpydoc",
+    "sphinx_autodoc_typehints",  # Automatically document param types (less noise in
+    # class signature)
 ]
 
-numpydoc_show_class_members = False
-autosummary_generate = True
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+autoclass_content = "both"  # Add __init__ doc (ie. params) to class summaries
+html_show_sourcelink = (
+    False  # Remove 'view source code' from top of page (for html, not python)
+)
+autodoc_inherit_docstrings = False  # If no docstring, inherit from base class
+set_type_checking_flag = True  # Enable 'expensive' imports for sphinx_autodoc_typehints
+nbsphinx_allow_errors = True  # Continue through Jupyter errors
+# autodoc_typehints = "description" # Sphinx-native method. Not as good as
+# sphinx_autodoc_typehints
+add_module_names = False  # Remove namespaces from class/method signatures
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -64,17 +71,19 @@
 # The master toctree document.
 master_doc = "index"
 
-templates_path = []  # ["_templates"]
+templates_path = ["_templates"]
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # intersphinx allows referencing other packages sphinx docs
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.9", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
     "astropy": ("https://docs.astropy.org/en/latest/", None),
-    "ctapipe": ("https://ctapipe.readthedocs.io/en/v0.19.3/", None),
-    "matplotlib": ("https://matplotlib.org/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
     "traitlets": ("https://traitlets.readthedocs.io/en/stable/", None),
+    "ctapipe": ("https://ctapipe.readthedocs.io/en/v0.19.3/", None),
 }
 
 # These links are ignored in the checks, necessary due to broken intersphinx for these
@@ -95,6 +104,8 @@
     ("py:class", "ClassesType"),
 ]
 
+suppress_warnings = ["autosummary"]
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
@@ -107,8 +118,6 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = f"{project}doc"
 
-html_logo = "_static/nectarcam.png"
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -123,6 +132,11 @@
 html_file_suffix = ".html"
 
 html_theme_options = {
+    "logo": {
+        "image_light": "_static/nectarcam_logo.webp",
+        "image_dark": "_static/nectarcam_logo_dark.webp",
+        "alt_text": "nectarchain",
+    },
     "navigation_with_keys": False,
     "github_url": f"https://github.com/cta-observatory/{project}",
     "navbar_start": ["navbar-logo", "version-switcher"],

diff --git a/docs/index.rst b/docs/index.rst
@@ -14,7 +14,7 @@ Welcome to nectarchain's documentation!
     :hidden:
 
     developer-guide/index
-    api-reference/index
+    API reference <_autosummary/nectarchain>
 
 
 Indices and tables

diff --git a/pyproject.toml b/pyproject.toml
@@ -48,6 +48,7 @@ dev = [
 
 docs = [
     "sphinx",
+    "sphinx-autodoc-typehints",
     "sphinx-automodapi",
     "pydata_sphinx_theme",
     "numpydoc",

diff --git a/src/nectarchain/data/container/eventSource.py b/src/nectarchain/data/container/eventSource.py
@@ -192,40 +192,45 @@ class LightNectarCAMEventSource(NectarCAMEventSource):
     LightNectarCAMEventSource is a subclass of NectarCAMEventSource that provides a
     generator for iterating over NectarCAM events.
 
-    This implementation of the NectarCAMEventSource is mucvh lighter than the one within
-    ctapipe_io_nectarcam, only the fileds interesting
-    for nectachain are kept.
-
-    Attributes:
-        input_url (str): The input URL of the data source.
-        max_events (int): The maximum number of events to process.
-        tel_id (int): The telescope ID.
-        nectarcam_service (NectarCAMService): The service container for NectarCAM.
-        trigger_information (bool): Flag indicating whether to fill trigger information
-        in the event container.
-        obs_ids (list): The list of observation IDs.
-        multi_file (MultiFileReader): The multi-file reader for reading the data source.
-        r0_r1_calibrator (R0R1Calibrator): The calibrator for R0 to R1 conversion.
-        calibrate_flatfields_and_pedestals (bool): Flag indicating whether to calibrate
-        flatfield and pedestal events.
-
-    Methods:
-        _generator: The generator function that yields NectarCAMDataContainer objects
-        representing each event.
-
+    This implementation of the NectarCAMEventSource is much lighter than the one within
+    ctapipe_io_nectarcam, only the fields interesting for nectarchain are kept.
+
+    Parameters
+    ----------
+    input_url : str
+        The input URL of the data source.
+    max_events : int
+        The maximum number of events to process.
+    tel_id : int
+        The telescope ID.
+    nectarcam_service : NectarCAMService
+        The service container for NectarCAM.
+    trigger_information : bool
+        Flag indicating whether to fill trigger information in the event container.
+    obs_ids : list
+        The list of observation IDs.
+    multi_file : MultiFileReader
+        The multi-file reader for reading the data source.
+    r0_r1_calibrator : R0R1Calibrator
+        The calibrator for R0 to R1 conversion.
+    calibrate_flatfields_and_pedestals : bool
+        Flag indicating whether to calibrate flatfield and pedestal events.
     """
 
     def _generator(self):
         """
         The generator function that yields NectarCAMDataContainer objects representing
         each event.
 
-        Yields:
-            NectarCAMDataContainer: The NectarCAMDataContainer object representing
-            each event.
+        Yields
+        ------
+        NectarCAMDataContainer :
+            The NectarCAMDataContainer object representing each event.
+
+        Raises
+        ------
+        None
 
-        Raises:
-            None
         """
         # container for NectarCAM data
         array_event = NectarCAMDataContainer()