Update docs

docs/_static/ctapipe.css

@@ -0,0 +1,47 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+
+/* sphinx-design */
+.sd-card {
+  border-radius: 5px;
+  padding: 30px 10px 20px 10px;
+  margin: 10px 0px;
+}
+
+.sd-card .sd-card-header .sd-card-text {
+  margin: 0px;
+}
+
+.sd-card .sd-card-header {
+  border: none;
+  text-align: center;
+  font-size: var(--pst-font-size-h4);
+  font-weight: bold;
+  padding: 0.5rem 0rem 0.5rem 0rem;
+}
+
+.sd-card .sd-card-footer {
+  border: none;
+}
+
+.sd-card .sd-card-footer .sd-card-text {
+  max-width: 220px;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+html[data-theme="dark"] .sd-shadow-sm {
+  --sd-color-shadow: #6e6e6e
+}
+

docs/_static/switcher.json

@@ -0,0 +1,72 @@
+[
+  {
+    "name": "dev",
+    "version": "latest",
+    "url": "https://ctapipe.readthedocs.io/en/latest/"
+  },
+  {
+    "name": "v0.19.2 (stable)",
+    "version": "stable",
+    "url": "https://ctapipe.readthedocs.io/en/stable/"
+  },
+  {
+    "name": "v0.19.3",
+    "version": "v0.19.3",
+    "url": "https://ctapipe.readthedocs.io/en/v0.19.3/"
+  },
+  {
+    "name": "v0.19.2",
+    "version": "v0.19.2",
+    "url": "https://ctapipe.readthedocs.io/en/v0.19.2/"
+  },
+  {
+    "name": "v0.19.1",
+    "version": "v0.19.1",
+    "url": "https://ctapipe.readthedocs.io/en/v0.19.1/"
+  },
+  {
+    "name": "v0.19.0",
+    "version": "v0.19.0",
+    "url": "https://ctapipe.readthedocs.io/en/v0.19.0/"
+  },
+  {
+    "name": "v0.18.1",
+    "version": "v0.18.1",
+    "url": "https://ctapipe.readthedocs.io/en/v0.18.1/"
+  },
+  {
+    "name": "v0.18.0",
+    "version": "v0.18.0",
+    "url": "https://ctapipe.readthedocs.io/en/v0.18.0/"
+  },
+  {
+    "name": "v0.17.0",
+    "version": "v0.17.0",
+    "url": "https://ctapipe.readthedocs.io/en/v0.17.0/"
+  },
+  {
+    "name": "v0.16.0",
+    "version": "v0.16.0",
+    "url": "https://ctapipe.readthedocs.io/en/v0.16.0/"
+  },
+  {
+    "name": "v0.15.0",
+    "version": "v0.15.0",
+    "url": "https://ctapipe.readthedocs.io/en/v0.15.0/"
+  },
+  {
+    "name": "v0.14.0",
+    "version": "v0.14.0",
+    "url": "https://ctapipe.readthedocs.io/en/v0.14.0/"
+  },
+  {
+    "name": "v0.12.0-rtd",
+    "version": "v0.12.0-rtd",
+    "url": "https://ctapipe.readthedocs.io/en/v0.12.0-rtd/"
+  },
+  {
+    "name": "v0.11.0-rtd",
+    "version": "v0.11.0-rtd",
+    "url": "https://ctapipe.readthedocs.io/en/v0.11.0-rtd/"
+  }
+]

docs/changes/2373.maintenance.rst

@@ -0,0 +1,3 @@
+* Switched to ``PyData`` theme for docs
+* Updated ``Sphinx`` to version 6.2.1
+* Updated front page of docs

docs/conf.py

@@ -36,6 +36,7 @@
 setup_metadata = dict(setup_cfg.items("metadata"))
 setup_options = dict(setup_cfg.items("options"))
 
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -52,10 +53,13 @@
     "nbsphinx",
     "matplotlib.sphinxext.plot_directive",
     "numpydoc",
+    "sphinx_design",
     "IPython.sphinxext.ipython_console_highlighting",
 ]
 
+
 numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
 nbsphinx_timeout = 200  # allow max 2 minutes to build each notebook
 
 
@@ -67,6 +71,8 @@ def setup(app):
     # fix trait aliases generating doc warnings
     from ctapipe.core import traits
 
+    app.add_css_file("_static/ctapipe.css")
+
     aliases = [
         "flag",
         "observe",
@@ -122,6 +128,17 @@ def setup(app):
     ("py:class", "ctapipe.compat.StrEnum"),
 ]
 
+# temporary workaround to ignore reference warnings and ensure build
+nitpick_ignore += [
+    ("py:obj", "ctapipe.calib.CameraCalibrator"),
+    ("py:obj", "ctapipe.calib.GainSelector"),
+    ("py:obj", "CameraGeometry"),
+    ("py:obj", "ctapipe.instrument.camera.CameraGeometry"),
+    ("py:obj", "ctapipe.instrument.camera.CameraDescription"),
+    ("py:obj", "ctapipe.instrument.camera.PixelShape"),
+    ("py:obj", "ctapipe.instrument.camera.CameraReadout"),
+]
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -182,32 +199,86 @@ def setup(app):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+
+# -- Version switcher -----------------------------------------------------
+
+# Define the json_url for our version switcher.
+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")
+# 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.
+    release = ctapipe.__version__
+    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
+
+
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "default"
+# on_rtd is whether we are on readthedocs.org
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+
+html_theme = "pydata_sphinx_theme"
+
+
+html_favicon = "_static/favicon.ico"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "logo": {
+        "image_light": "ctapipe_logo.webp",
+        "image_dark": "ctapipe_logo_dark.webp",
+        "alt_text": "ctapipe",
+    },
+    "github_url": "https://github.com/cta-observatory/ctapipe",
+    "header_links_before_dropdown": 6,
+    "navbar_start": ["navbar-logo", "version-switcher"],
+    "switcher": {
+        "version_match": version_match,
+        "json_url": json_url,
+    },
+    "use_edit_page_button": True,
+    "icon_links": [
+        {
+            "name": "CTA Observatory",
+            "url": "https://www.cta-observatory.org/",
+            "type": "url",
+            "icon": "https://www.cta-observatory.org/wp-content/themes/ctao/favicon.ico",
+        },
+    ],
+}
+
+html_sidebars = {
+    "**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"],
+    "index.rst": [],
+}
+
 
 # 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".
 # html_static_path = ['_static']
 html_static_path = ["_static"]
-
 html_context = {
-    "css_files": ["_static/theme_overrides.css"]  # override wide tables in RTD theme
+    "default_mode": "light",
+    "github_user": "cta-observatory",
+    "github_repo": "ctapipe",
+    "github_version": "main",
+    "doc_path": "docs",
 }
-
-html_favicon = "_static/favicon.ico"
-# -- Options for HTMLHelp output ------------------------------------------
-
+html_css_files = ["ctapipe.css"]
+html_file_suffix = ".html"
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -216,6 +287,7 @@ def setup(app):
 # Output file base name for HTML help builder.
 htmlhelp_basename = project + "doc"
 
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -277,19 +349,3 @@ def setup(app):
     "iminuit": ("https://iminuit.readthedocs.io/en/latest/", None),
     "traitlets": ("https://traitlets.readthedocs.io/en/stable/", None),
 }
-
-# on_rtd is whether we are on readthedocs.org
-on_rtd = os.environ.get("READTHEDOCS", None) == "True"
-
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    try:
-        import sphinx_rtd_theme
-    except ImportError:
-        raise ImportError(
-            "It looks like you don't have the sphinx_rtd_theme "
-            "package installed. This documentation "
-            "uses the Read The Docs theme, so you must install this "
-            "first. For example, pip install sphinx_rtd_theme"
-        )
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

docs/ctapipe_api/calib/index.rst

@@ -46,3 +46,4 @@ Reference/API
 
 .. automodapi:: ctapipe.calib
     :no-inheritance-diagram:
+    :noindex:

docs/ctapipe_api/calib/index_camera.rst

@@ -19,7 +19,7 @@ CTA Cameras (MC, prototypes and final camera calibration algorithms).
 CameraCalibrator
 ****************
 
-The primary class in this module is the `CameraCalibrator`. This class handles
+The primary class in this module is the :class:`.CameraCalibrator`. This class handles
 two data level transition stages for the event:
 
 * R1 -> DL0 (:ref:`image_reducers`)

docs/ctapipe_api/instrument/camera.rst

@@ -22,5 +22,6 @@ Reference/API
 
 .. automodapi:: ctapipe.instrument.camera
     :no-inheritance-diagram:
+
 .. automodapi:: ctapipe.instrument.camera.description
     :no-inheritance-diagram:

docs/ctapipe_api/instrument/camera_readout.rst

@@ -32,8 +32,8 @@ Input/Output
 
 
 You can write out a `CameraReadout` by using the ``CameraReadout.to_table()``
- method to turn it into a `~astropy.table.Table`, and then call its ``write()``
-  function.  Reading it back in can be done with ``CameraReadout.from_table()``.
+method to turn it into a `~astropy.table.Table`, and then call its ``write()``
+function.  Reading it back in can be done with ``CameraReadout.from_table()``.
 
 .. code-block:: python