Merge pull request #2373 from aknierim/update-docs

Update docs

ctapipe/calib/camera/__init__.py

@@ -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",
 ]

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>")

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(

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",

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",
 ]

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",
 ]

docs/_static/ctapipe.css

@@ -0,0 +1,67 @@
+/* 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;
+   }
+}
+
+.version-switcher__container a[data-version-name*="stable"] {
+  background-color: #E9F6EC;
+  color: #28A745;
+}
+
+.version-switcher__container a[data-version-name*="dev"] {
+  background-color: #FDF4EB;
+  color: #EE9040;
+}
+
+html[data-theme="dark"] .version-switcher__container a[data-version-name*="stable"] {
+  background-color: #222924;
+  color: #28A745;
+}
+
+html[data-theme="dark"] .version-switcher__container a[data-version-name*="dev"] {
+  background-color: #332A21;
+  color: #EE9040;
+}
+
+
+/* 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": "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