cta-observatory · maxnoe · Jul 20, 2023 · Jul 4, 2023 · Jul 4, 2023 · Jul 4, 2023
@@ -3,10 +3,10 @@
 Camera calibration module.
 """
 
-from .calibrator import CameraCalibrator
-from .gainselection import GainSelector
+from .calibrator import CameraCalibrator  # noqa: F401
+from .gainselection import GainSelector  # noqa: F401
 
 __all__ = [
-    "CameraCalibrator",
-    "GainSelector",
+    # "CameraCalibrator",
+    # "GainSelector",
 ]
diff --git a/ctapipe/core/component.py b/ctapipe/core/component.py
@@ -1,4 +1,5 @@
 """ Class to handle configuration for algorithms """
+import html
 import warnings
 import weakref
 from abc import ABCMeta
@@ -233,9 +234,9 @@ def _repr_html_(self):
             or "Undocumented"
         )
         lines = [
-            "<div style='border:1px solid black; max-width: 700px; padding:2em'; word-wrap:break-word;>",
+            '<div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">',
             f"<b>{name}</b>",
-            f"<p> {docstring} </p>",
+            docstring,
             "<table>",
             "    <colgroup>",
             "        <col span='1' style=' '>",
@@ -246,21 +247,23 @@ def _repr_html_(self):
         ]
         for key, val in self.get_current_config()[name].items():
             htmlval = (
-                str(val).replace("/", "/<wbr>").replace("_", "_<wbr>")
+                html.escape(str(val)).replace("/", "/<wbr>").replace("_", "_<wbr>")
             )  # allow breaking at boundary
 
             # traits of the current component
             if key in traits:
-                thehelp = f"{traits[key].help} (default: {traits[key].default_value})"
+                thehelp = html.escape(
+                    f"{traits[key].help} (default: {traits[key].default_value})"
+                )
                 lines.append(f"<tr><th>{key}</th>")
                 if val != traits[key].default_value:
                     lines.append(
-                        f"<td style='text-align: left;'><span style='color:blue; max-width:30em;'>{htmlval}</span></td>"
+                        f'<td style="text-align: left;"><span style="color:blue; max-width:30em;">{htmlval}</span></td>'
                     )
                 else:
-                    lines.append(f"<td style='text-align: left;'>{htmlval}</td>")
+                    lines.append(f'<td style="text-align: left;">{htmlval}</td>')
                 lines.append(
-                    f"<td style='text-align: left;'><i>{thehelp}</i></td></tr>"
+                    f'<td style="text-align: left;"><i>{thehelp}</i></td></tr>'
                 )
         lines.append("    </tbody>")
         lines.append("</table>")

diff --git a/ctapipe/core/tool.py b/ctapipe/core/tool.py
@@ -1,4 +1,5 @@
 """Classes to handle configurable command-line user interfaces."""
+import html
 import logging
 import logging.config
 import os
@@ -495,8 +496,9 @@ def _repr_html_(self):
             or "Undocumented"
         )
         lines = [
+            '<div style="border:1px solid black; max-width: 700px; padding:2em; word-wrap:break-word;">',
             f"<b>{name}</b>",
-            f"<p> {docstring} </p>",
+            docstring,
             "<table>",
             "    <colgroup>",
             "        <col span='1' style=' '>",
@@ -507,12 +509,14 @@ def _repr_html_(self):
         ]
         for key, val in self.get_current_config()[name].items():
             htmlval = (
-                str(val).replace("/", "/<wbr>").replace("_", "_<wbr>")
+                html.escape(str(val)).replace("/", "/<wbr>").replace("_", "_<wbr>")
             )  # allow breaking at boundary
 
             # traits of the current component
             if key in traits:
-                thehelp = f"{traits[key].help} (default: {traits[key].default_value})"
+                thehelp = html.escape(
+                    f"{traits[key].help} (default: {traits[key].default_value})"
+                )
                 lines.append(f"<tr><th>{key}</th>")
                 if val != traits[key].default_value:
                     lines.append(

diff --git a/ctapipe/image/__init__.py b/ctapipe/image/__init__.py
@@ -42,6 +42,7 @@
 )
 from .muon import (
     MuonIntensityFitter,
+    MuonProcessor,
     MuonRingFitter,
     intensity_ratio_inside_ring,
     kundu_chaudhuri_circle_fit,
@@ -93,6 +94,7 @@
     "chi_squared",
     "MuonIntensityFitter",
     "MuonRingFitter",
+    "MuonProcessor",
     "kundu_chaudhuri_circle_fit",
     "mean_squared_error",
     "intensity_ratio_inside_ring",

diff --git a/ctapipe/image/muon/__init__.py b/ctapipe/image/muon/__init__.py
@@ -5,17 +5,14 @@
     ring_containment,
 )
 from .fitting import kundu_chaudhuri_circle_fit
-from .intensity_fitter import MuonIntensityFitter
-from .processor import MuonProcessor
-from .ring_fitter import MuonRingFitter
+from .intensity_fitter import MuonIntensityFitter  # noqa: F401
+from .processor import MuonProcessor  # noqa: F401
+from .ring_fitter import MuonRingFitter  # noqa: F401
 
 __all__ = [
-    "MuonIntensityFitter",
-    "MuonRingFitter",
     "kundu_chaudhuri_circle_fit",
     "mean_squared_error",
     "intensity_ratio_inside_ring",
     "ring_completeness",
     "ring_containment",
-    "MuonProcessor",
 ]
diff --git a/ctapipe/instrument/camera/__init__.py b/ctapipe/instrument/camera/__init__.py
@@ -1,11 +1,12 @@
-from .description import CameraDescription
-from .geometry import CameraGeometry, UnknownPixelShapeWarning, PixelShape
-from .readout import CameraReadout
+from .description import CameraDescription  # noqa: F401
+from .geometry import CameraGeometry, PixelShape, UnknownPixelShapeWarning  # noqa: F401
+from .readout import CameraReadout  # noqa: F401
 
+# commented out due to sphinx issue with classes being defined in 3 places
 __all__ = [
-    "CameraDescription",
-    "CameraGeometry",
-    "PixelShape",
-    "UnknownPixelShapeWarning",
-    "CameraReadout",
+    # "CameraDescription",
+    # "CameraGeometry",
+    # "PixelShape",
+    # "UnknownPixelShapeWarning",
+    # "CameraReadout",
 ]
diff --git a/docs/_static/ctapipe.css b/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;
+}
+
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
diff --git a/docs/changes/2373.maintenance.rst b/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
diff --git a/docs/conf.py b/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
 
 
@@ -64,6 +68,8 @@
 
 
 def setup(app):
+    app.add_css_file("ctapipe.css")
+
     # fix trait aliases generating doc warnings
     from ctapipe.core import traits
 
@@ -122,6 +128,7 @@ def setup(app):
     ("py:class", "ctapipe.compat.StrEnum"),
 ]
 
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -182,32 +189,53 @@ def setup(app):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+
 # -- 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"
+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"],
+    "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"]}
+
 
 # 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 +244,7 @@ def setup(app):
 # Output file base name for HTML help builder.
 htmlhelp_basename = project + "doc"
 
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -277,19 +306,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()]
diff --git a/docs/ctapipe_api/calib/index.rst b/docs/ctapipe_api/calib/index.rst
@@ -1,8 +1,9 @@
 .. _calib:
 
-===============================
- Calibration (`~ctapipe.calib`)
-===============================
+
+==============================
+Calibration (`~ctapipe.calib`)
+==============================
 
 .. currentmodule:: ctapipe.calib
 

diff --git a/docs/ctapipe_api/calib/index_camera.rst b/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 `~ctapipe.calib.camera.calibrator.CameraCalibrator`. This class handles
 two data level transition stages for the event:
 
 * R1 -> DL0 (:ref:`image_reducers`)

diff --git a/docs/ctapipe_api/instrument/camera.rst b/docs/ctapipe_api/instrument/camera.rst
@@ -5,8 +5,8 @@
 Camera Description
 ==================
 
-The `CameraDescription` contains classes holding information about the
-Cherenkov camera, namely the `CameraGeometry` and `CameraReadout` classes.
+The `~camera.description.CameraDescription` contains classes holding information about the
+Cherenkov camera, namely the `~camera.geometry.CameraGeometry` and `~camera.readout.CameraReadout` classes.
 
 
 .. toctree::
@@ -17,10 +17,10 @@ Cherenkov camera, namely the `CameraGeometry` and `CameraReadout` classes.
 
 
 Reference/API
--------------
-
+=============
 
 .. automodapi:: ctapipe.instrument.camera
     :no-inheritance-diagram:
+
 .. automodapi:: ctapipe.instrument.camera.description
     :no-inheritance-diagram: