Merge pull request #2383 from cta-observatory/update_dev_docs

Update doc structure and dev guide
cta-observatory · Sep 6, 2023 · 9c2d0d2 · 9c2d0d2
2 parents 20f2032 + cfc144a
commit 9c2d0d2
Show file tree

Hide file tree

Showing 101 changed files with 740 additions and 658 deletions.
diff --git a/ctapipe/calib/__init__.py b/ctapipe/calib/__init__.py
@@ -1,7 +1,10 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 """
-Calibration
+Module for calibration code
 """
 from .camera import CameraCalibrator, GainSelector
 
-__all__ = ["CameraCalibrator", "GainSelector"]
+__all__ = [
+    "CameraCalibrator",
+    "GainSelector",
+]
diff --git a/docs/ctapipe_logo.png → docs/_static/ctapipe_logo.png b/docs/ctapipe_logo.png → docs/_static/ctapipe_logo.png
diff --git a/docs/ctapipe_logo.webp → docs/_static/ctapipe_logo.webp b/docs/ctapipe_logo.webp → docs/_static/ctapipe_logo.webp
diff --git a/docs/ctapipe_logo_dark.webp → docs/_static/ctapipe_logo_dark.webp b/docs/ctapipe_logo_dark.webp → docs/_static/ctapipe_logo_dark.webp
diff --git a/docs/ctapipe_api/atmosphere/index.rst → docs/api-reference/atmosphere/index.rst b/docs/ctapipe_api/atmosphere/index.rst → docs/api-reference/atmosphere/index.rst
diff --git a/docs/ctapipe_api/calib/index_camera.rst → docs/api-reference/calib/camera.rst b/docs/ctapipe_api/calib/index_camera.rst → docs/api-reference/calib/camera.rst
@@ -22,14 +22,13 @@ CameraCalibrator
 The primary class in this module is the `~ctapipe.calib.camera.calibrator.CameraCalibrator`. This class handles
 two data level transition stages for the event:
 
-* R1 -> DL0 (:ref:`image_reducers`)
-* DL0 -> DL1 (:ref:`image_charge_extractors`)
+* R1 → DL0 (:ref:`image_reducers`)
+* DL0 → DL1 (:ref:`image_charge_extractors`)
 
 The class takes a ctapipe event container, and fills the
 next data level containers with the calibrated information.
 
-See the `CTA High-Level Data Model Definitions SYS-QA/160517
-<https://jama.cta-observatory.org/perspective.req?projectId=6&docId=26528>`_ document (CTA internal) for information about the
+See the `CTA Top-Level Data Model Definitions <https://redmine.cta-observatory.org/dmsf/files/16325/view>`_ document (CTA internal) for information about the
 different data levels.
 
 

diff --git a/docs/ctapipe_api/calib/index.rst → docs/api-reference/calib/index.rst b/docs/ctapipe_api/calib/index.rst → docs/api-reference/calib/index.rst
@@ -13,32 +13,19 @@ Introduction
 
 This module include all the functions and classes needed for the Calibration of CTA data.
 
-It consists in four main sub-modules:
-
-* :ref:`calib_camera`
-
-* Array Calibration
-
-* Atmosphere Calibration
-
-* Pointing Calibration
+Currently, only code related to :ref:`calib_camera` is implemented here.
 
 For more information on where you should implement your code, please have a look to the README.rst files inside each directory.
 
 
-Getting Started
-===============
-
-TODO: add examples.
-
 Submodules
 ==========
 
 .. toctree::
   :maxdepth: 1
   :glob:
 
-  index_*
+  camera
 
 
 

diff --git a/docs/ctapipe_api/containers/index.rst → docs/api-reference/containers/index.rst b/docs/ctapipe_api/containers/index.rst → docs/api-reference/containers/index.rst
diff --git a/docs/ctapipe_api/coordinates/index.rst → docs/api-reference/coordinates/index.rst b/docs/ctapipe_api/coordinates/index.rst → docs/api-reference/coordinates/index.rst
@@ -38,7 +38,7 @@ they can be transformed to and from any other `astropy.coordinates` frame, like
 
 The three different coordinate frames are shown here:
 
-.. plot:: ctapipe_api/coordinates/plot_camera_frames.py
+.. plot:: api-reference/coordinates/plot_camera_frames.py
 
 
 The `CameraFrame` is used internally in ``ctapipe`` and comes from ``sim_telarray``.

diff --git a/...ipe_api/coordinates/plot_camera_frames.py → ...ference/coordinates/plot_camera_frames.py b/...ipe_api/coordinates/plot_camera_frames.py → ...ference/coordinates/plot_camera_frames.py
diff --git a/docs/ctapipe_api/core/corediagram.dot → docs/api-reference/core/corediagram.dot b/docs/ctapipe_api/core/corediagram.dot → docs/api-reference/core/corediagram.dot
diff --git a/docs/ctapipe_api/core/index.rst → docs/api-reference/core/index.rst b/docs/ctapipe_api/core/index.rst → docs/api-reference/core/index.rst
diff --git a/docs/ctapipe_api/core/tool-component.pdf → docs/api-reference/core/tool-component.pdf b/docs/ctapipe_api/core/tool-component.pdf → docs/api-reference/core/tool-component.pdf
diff --git a/docs/ctapipe_api/core/tool-component.png → docs/api-reference/core/tool-component.png b/docs/ctapipe_api/core/tool-component.png → docs/api-reference/core/tool-component.png
diff --git a/docs/ctapipe_api/core/traits.rst → docs/api-reference/core/traits.rst b/docs/ctapipe_api/core/traits.rst → docs/api-reference/core/traits.rst
diff --git a/...age/TwoPassWindowSum_1st_pass_example.png → ...age/TwoPassWindowSum_1st_pass_example.png b/...age/TwoPassWindowSum_1st_pass_example.png → ...age/TwoPassWindowSum_1st_pass_example.png
diff --git a/docs/ctapipe_api/image/cleaning.rst → docs/api-reference/image/cleaning.rst b/docs/ctapipe_api/image/cleaning.rst → docs/api-reference/image/cleaning.rst
diff --git a/docs/ctapipe_api/image/dilate.png → docs/api-reference/image/dilate.png b/docs/ctapipe_api/image/dilate.png → docs/api-reference/image/dilate.png
diff --git a/docs/ctapipe_api/image/extractor.rst → docs/api-reference/image/extractor.rst b/docs/ctapipe_api/image/extractor.rst → docs/api-reference/image/extractor.rst
diff --git a/docs/ctapipe_api/image/hillas.rst → docs/api-reference/image/hillas.rst b/docs/ctapipe_api/image/hillas.rst → docs/api-reference/image/hillas.rst
diff --git a/docs/ctapipe_api/image/index.rst → docs/api-reference/image/index.rst b/docs/ctapipe_api/image/index.rst → docs/api-reference/image/index.rst
diff --git a/docs/ctapipe_api/image/invalid_pixels.rst → docs/api-reference/image/invalid_pixels.rst b/docs/ctapipe_api/image/invalid_pixels.rst → docs/api-reference/image/invalid_pixels.rst
diff --git a/docs/ctapipe_api/image/modifications.rst → docs/api-reference/image/modifications.rst b/docs/ctapipe_api/image/modifications.rst → docs/api-reference/image/modifications.rst
diff --git a/docs/ctapipe_api/image/muon.rst → docs/api-reference/image/muon.rst b/docs/ctapipe_api/image/muon.rst → docs/api-reference/image/muon.rst
diff --git a/docs/ctapipe_api/image/pixel_likelihood.rst → .../api-reference/image/pixel_likelihood.rst b/docs/ctapipe_api/image/pixel_likelihood.rst → .../api-reference/image/pixel_likelihood.rst
diff --git a/docs/ctapipe_api/image/reducers.rst → docs/api-reference/image/reducers.rst b/docs/ctapipe_api/image/reducers.rst → docs/api-reference/image/reducers.rst
diff --git a/docs/ctapipe_api/image/toymodel.rst → docs/api-reference/image/toymodel.rst b/docs/ctapipe_api/image/toymodel.rst → docs/api-reference/image/toymodel.rst
diff --git a/docs/ctapipe_api/index.rst → docs/api-reference/index.rst b/docs/ctapipe_api/index.rst → docs/api-reference/index.rst
diff --git a/docs/ctapipe_api/instrument/camera.rst → docs/api-reference/instrument/camera.rst b/docs/ctapipe_api/instrument/camera.rst → docs/api-reference/instrument/camera.rst
diff --git a/...tapipe_api/instrument/camera_geometry.rst → ...-reference/instrument/camera_geometry.rst b/...tapipe_api/instrument/camera_geometry.rst → ...-reference/instrument/camera_geometry.rst
@@ -79,7 +79,7 @@ with `numpy` operations, since it is quite speed-efficient.
 Examples
 --------
 
-.. plot:: ctapipe_api/instrument/camerageometry_example.py
+.. plot:: api-reference/instrument/camerageometry_example.py
     :include-source:
 
 

diff --git a/...ctapipe_api/instrument/camera_readout.rst → ...i-reference/instrument/camera_readout.rst b/...ctapipe_api/instrument/camera_readout.rst → ...i-reference/instrument/camera_readout.rst
diff --git a/..._api/instrument/camerageometry_example.py → ...ence/instrument/camerageometry_example.py b/..._api/instrument/camerageometry_example.py → ...ence/instrument/camerageometry_example.py
diff --git a/docs/ctapipe_api/instrument/config.dot → docs/api-reference/instrument/config.dot b/docs/ctapipe_api/instrument/config.dot → docs/api-reference/instrument/config.dot
diff --git a/docs/ctapipe_api/instrument/index.rst → docs/api-reference/instrument/index.rst b/docs/ctapipe_api/instrument/index.rst → docs/api-reference/instrument/index.rst
diff --git a/docs/ctapipe_api/instrument/optics.rst → docs/api-reference/instrument/optics.rst b/docs/ctapipe_api/instrument/optics.rst → docs/api-reference/instrument/optics.rst
diff --git a/docs/ctapipe_api/instrument/subarray.rst → docs/api-reference/instrument/subarray.rst b/docs/ctapipe_api/instrument/subarray.rst → docs/api-reference/instrument/subarray.rst
diff --git a/docs/ctapipe_api/instrument/telescope.rst → docs/api-reference/instrument/telescope.rst b/docs/ctapipe_api/instrument/telescope.rst → docs/api-reference/instrument/telescope.rst
diff --git a/docs/ctapipe_api/io/index.rst → docs/api-reference/io/index.rst b/docs/ctapipe_api/io/index.rst → docs/api-reference/io/index.rst
diff --git a/docs/ctapipe_api/io/shower.png → docs/api-reference/io/shower.png b/docs/ctapipe_api/io/shower.png → docs/api-reference/io/shower.png
diff --git a/docs/ctapipe_api/reco/ImPACT.rst → docs/api-reference/reco/ImPACT.rst b/docs/ctapipe_api/reco/ImPACT.rst → docs/api-reference/reco/ImPACT.rst
diff --git a/...tapipe_api/reco/images/ImageTemplates.png → ...-reference/reco/images/ImageTemplates.png b/...tapipe_api/reco/images/ImageTemplates.png → ...-reference/reco/images/ImageTemplates.png
diff --git a/docs/ctapipe_api/reco/images/goodness.png → docs/api-reference/reco/images/goodness.png b/docs/ctapipe_api/reco/images/goodness.png → docs/api-reference/reco/images/goodness.png
diff --git a/docs/ctapipe_api/reco/images/likelihood.png → .../api-reference/reco/images/likelihood.png b/docs/ctapipe_api/reco/images/likelihood.png → .../api-reference/reco/images/likelihood.png
diff --git a/docs/ctapipe_api/reco/images/predictions.png → ...api-reference/reco/images/predictions.png b/docs/ctapipe_api/reco/images/predictions.png → ...api-reference/reco/images/predictions.png
diff --git a/docs/ctapipe_api/reco/index.rst → docs/api-reference/reco/index.rst b/docs/ctapipe_api/reco/index.rst → docs/api-reference/reco/index.rst
diff --git a/docs/ctapipe_api/reco/sklearn.rst → docs/api-reference/reco/sklearn.rst b/docs/ctapipe_api/reco/sklearn.rst → docs/api-reference/reco/sklearn.rst
diff --git a/docs/ctapipe_api/reco/stereo_combination.rst → ...api-reference/reco/stereo_combination.rst b/docs/ctapipe_api/reco/stereo_combination.rst → ...api-reference/reco/stereo_combination.rst
diff --git a/docs/ctapipe_api/tools/index.rst → docs/api-reference/tools/index.rst b/docs/ctapipe_api/tools/index.rst → docs/api-reference/tools/index.rst
diff --git a/docs/ctapipe_api/utils/index.rst → docs/api-reference/utils/index.rst b/docs/ctapipe_api/utils/index.rst → docs/api-reference/utils/index.rst
diff --git a/docs/ctapipe_api/visualization/index.rst → docs/api-reference/visualization/index.rst b/docs/ctapipe_api/visualization/index.rst → docs/api-reference/visualization/index.rst
diff --git a/docs/cameras.png b/docs/cameras.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -101,6 +101,19 @@ def setup(app):
 # These links are ignored in the checks, necessary due to broken intersphinx for
 # these
 nitpick_ignore = [
+    # needed for building the docs with python 3.11 locally.
+    # we use the lowest supported version on readthedocs, so that is what we use the intersphinx
+    # link above
+    ("py:class", "enum.StrEnum"),
+    # these are coming from traitlets:
+    ("py:class", "t.Union"),
+    ("py:class", "t.Any"),
+    ("py:class", "t.Dict"),
+    ("py:class", "t.Optional"),
+    ("py:class", "t.Type"),
+    ("py:class", "t.List"),
+    ("py:class", "t.Tuple"),
+    ("py:class", "Config"),
     ("py:class", "traitlets.config.configurable.Configurable"),
     ("py:class", "traitlets.traitlets.HasTraits"),
     ("py:class", "traitlets.traitlets.HasDescriptors"),
@@ -126,6 +139,7 @@ def setup(app):
     ("py:class", "astropy.table.table.Table"),
     ("py:class", "eventio.simtel.simtelfile.SimTelFile"),
     ("py:class", "ctapipe.compat.StrEnum"),
+    ("py:class", "ctapipe.compat.StrEnum"),
 ]
 
 
@@ -196,19 +210,19 @@ def setup(app):
 json_url = "https://ctapipe.readthedocs.io/en/latest/_static/switcher.json"
 
 # Define the version we use for matching in the version switcher.
-version_match = os.environ.get("READTHEDOCS_VERSION")
+version_match = os.getenv("READTHEDOCS_VERSION")
 # If READTHEDOCS_VERSION doesn't exist, we're not on RTD
 # If it is an integer, we're in a PR build and the version isn't correct.
 if not version_match or version_match.isdigit():
     # For local development, infer the version to match from the package.
     if "dev" in release or "rc" in release:
         version_match = "latest"
-        # We want to keep the relative reference if we are in dev mode
-        # but we want the whole url if we are effectively in a released version
-        json_url = "_static/switcher.json"
     else:
         version_match = release
 
+    # We want to keep the relative reference when on a pull request or locally
+    json_url = "_static/switcher.json"
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -222,8 +236,8 @@ def setup(app):
 # documentation.
 html_theme_options = {
     "logo": {
-        "image_light": "ctapipe_logo.webp",
-        "image_dark": "ctapipe_logo_dark.webp",
+        "image_light": "_static/ctapipe_logo.webp",
+        "image_dark": "_static/ctapipe_logo_dark.webp",
         "alt_text": "ctapipe",
     },
     "github_url": "https://github.com/cta-observatory/ctapipe",

diff --git a/docs/development/ceps/accepted/.keep → docs/developer-guide/ceps/accepted/.keep b/docs/development/ceps/accepted/.keep → docs/developer-guide/ceps/accepted/.keep
diff --git a/docs/development/ceps/accepted/cep-001.rst → ...developer-guide/ceps/accepted/cep-001.rst b/docs/development/ceps/accepted/cep-001.rst → ...developer-guide/ceps/accepted/cep-001.rst
diff --git a/docs/development/ceps/drafts/.keep → docs/developer-guide/ceps/drafts/.keep b/docs/development/ceps/drafts/.keep → docs/developer-guide/ceps/drafts/.keep
diff --git a/docs/development/ceps/index.rst → docs/developer-guide/ceps/index.rst b/docs/development/ceps/index.rst → docs/developer-guide/ceps/index.rst
@@ -1,43 +1,42 @@
-****************************
-Ctapipe Enhancment Proposals
-****************************
+*****************************
+ctapipe Enhancement Proposals
+*****************************
 
-CEPs (Ctapipe Enhancment Proposals) are short documents proposing and describing
+CEPs (ctapipe Enhancment Proposals) are short documents proposing and describing
 a major addition or change to ctapipe. See :ref:`cep-001` for further information.
 
 Below is a list of merged CEPs, i.e. the ones that are finalised,
 with status "accepted" or "rejected" or "withdrawn".
 The ones with "draft" status, i.e. that are under discussion,
-can be found on Github as `pull requests with the "CEP" label`_ .
+can be found on GitHub as `pull requests with the "CEP" label`_ .
 
 
 Accepted CEPs
 =============
 .. toctree::
-   :maxdepth: 1   
+   :maxdepth: 1
    :glob:
 
    accepted/*
 
 Proposed CEPs
 =============
-.. 
+..
    toctree::
-   :maxdepth: 1   
+   :maxdepth: 1
    :glob:
 
    proposed/*
 
 Rejected CEPs
 =============
 
-.. 
+..
    toctree::
-   :maxdepth: 1   
+   :maxdepth: 1
    :glob:
 
    rejected/*
 
 
 .. _pull requests with the "cep" label: https://github.com/cta-observatory/ctapipe/issues?q=label%3ACEP
-
diff --git a/docs/development/ceps/rejected/.keep → docs/developer-guide/ceps/rejected/.keep b/docs/development/ceps/rejected/.keep → docs/developer-guide/ceps/rejected/.keep
diff --git a/docs/development/code-guidelines.rst → docs/developer-guide/code-guidelines.rst b/docs/development/code-guidelines.rst → docs/developer-guide/code-guidelines.rst