cta-observatory · jlenain · Jul 31, 2024 · Jul 30, 2024 · Jul 30, 2024 · Jul 30, 2024
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,6 +23,8 @@ jobs:
     steps:
       - name: Check out source repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Set up Python environment
         uses: actions/setup-python@v5
         with:
@@ -82,7 +84,7 @@ jobs:
 
       - name: Mamba setup
         if: matrix.install-method == 'mamba'
-        uses: mamba-org/provision-with-micromamba@v16
+        uses: mamba-org/setup-micromamba@v1
         with:
           environment-name: "ci"
           environment-file: environment.yml

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/environment.yml b/environment.yml
@@ -13,7 +13,7 @@ dependencies:
   - pytest-runner
   - pip
   - pandas
-  - scipy=1.11
+  - scipy=1.11.4
   - sphinx
   - sphinx-automodapi
   - pydata-sphinx-theme

diff --git a/pyproject.toml b/pyproject.toml
@@ -24,7 +24,7 @@ dependencies = [
     "ctapipe~=0.19",
     "ctapipe-io-nectarcam",
     "pandas",
-    "scipy==1.11",
+    "scipy==1.11.4",
     "zodb",
     "zeo",
 ]
@@ -48,6 +48,7 @@ dev = [
 
 docs = [
     "sphinx",
+    "sphinx-autodoc-typehints",
     "sphinx-automodapi",
     "pydata_sphinx_theme",
     "numpydoc",
-Original file line number
+Diff line change
@@ Expand Up / @@ -92,6 +92,7 @@ src/nectarchain/user_scripts/**/test @@
     **.log
     **.pdf
     **.csv
+    **.png
     #VScode
     .vscode/
@@ Expand Down @@