diff --git a/ctapipe/calib/camera/__init__.py b/ctapipe/calib/camera/__init__.py index d576bafd0c0..b5b41267892 100644 --- a/ctapipe/calib/camera/__init__.py +++ b/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", ] diff --git a/ctapipe/core/component.py b/ctapipe/core/component.py index caee11edef7..b3b5b91a733 100644 --- 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 = [ - "
", + '
', f"{name}", - f"

{docstring}

", + docstring, "", " ", " ", @@ -246,21 +247,23 @@ def _repr_html_(self): ] for key, val in self.get_current_config()[name].items(): htmlval = ( - str(val).replace("/", "/").replace("_", "_") + html.escape(str(val)).replace("/", "/").replace("_", "_") ) # 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"") if val != traits[key].default_value: lines.append( - f"" + f'' ) else: - lines.append(f"") + lines.append(f'') lines.append( - f"" + f'' ) lines.append(" ") lines.append("
{key}{htmlval}{htmlval}{htmlval}{htmlval}{thehelp}
{thehelp}
") diff --git a/ctapipe/core/tool.py b/ctapipe/core/tool.py index 5f6744d2c95..5d28c1585a3 100644 --- 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 = [ + '
', f"{name}", - f"

{docstring}

", + docstring, "", " ", " ", @@ -507,12 +509,14 @@ def _repr_html_(self): ] for key, val in self.get_current_config()[name].items(): htmlval = ( - str(val).replace("/", "/").replace("_", "_") + html.escape(str(val)).replace("/", "/").replace("_", "_") ) # 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"") if val != traits[key].default_value: lines.append( diff --git a/ctapipe/image/__init__.py b/ctapipe/image/__init__.py index 3f8f32fc6d6..61799ac01a5 100644 --- 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 index f7025eb10a3..4d35282377c 100644 --- 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 index 678ea988577..e64c4e0db10 100644 --- 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 new file mode 100644 index 00000000000..30483b997f2 --- /dev/null +++ b/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; +} diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json new file mode 100644 index 00000000000..f2c980b19f7 --- /dev/null +++ b/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/" + } +] diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css deleted file mode 100644 index 63ee6cc74ce..00000000000 --- a/docs/_static/theme_overrides.css +++ /dev/null @@ -1,13 +0,0 @@ -/* 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; - } -} diff --git a/docs/changes/2373.maintenance.rst b/docs/changes/2373.maintenance.rst new file mode 100644 index 00000000000..8e5a70349d3 --- /dev/null +++ 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 index f2cb9a72486..4c228dc4886 100644 --- 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,80 @@ 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. + 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" +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_label": "Quick Links", + "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", + }, + ], + "announcement": """ +

ctapipe is not stable yet, so expect large and rapid + changes to structure and functionality as we explore various + design choices before the 1.0 release.

+ """, +} # 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 # " v documentation". @@ -216,6 +271,7 @@ def setup(app): # Output file base name for HTML help builder. htmlhelp_basename = project + "doc" + # -- Options for LaTeX output --------------------------------------------- latex_elements = { @@ -277,19 +333,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 index c4decc21eef..398acfed120 100644 --- 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 index d5cea730106..0827c266218 100644 --- 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 index 0b45cad8fa0..86fdd59a431 100644 --- 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: diff --git a/docs/ctapipe_api/instrument/camera_geometry.rst b/docs/ctapipe_api/instrument/camera_geometry.rst index 94336be2760..ddf30ae6e8c 100644 --- a/docs/ctapipe_api/instrument/camera_geometry.rst +++ b/docs/ctapipe_api/instrument/camera_geometry.rst @@ -5,7 +5,7 @@ Camera Geometries ================= -The `CameraGeometry` provides an easy way to work with images or data +The `~ctapipe.instrument.CameraGeometry` provides an easy way to work with images or data cubes related to Cherenkov Cameras. In *ctapipe*, a camera image is simply a flat 1D array (or 2D if time information is included), where there is one value per pixel. Of course, to work with such an array, @@ -14,38 +14,38 @@ Since CTA has at least 6 different camera types, and may have multiple versions of each as revisions are made, it is necessary to have a common way to describe all cameras. -So far there are several ways to construct a `CameraGeometry`: +So far there are several ways to construct a `~ctapipe.instrument.CameraGeometry`: -* `~ctapipe.io.EventSource` instances have a ``subarray`` attribute, +* `~ctapipe.io.EventSource` instances have a :attr:`~ctapipe.io.EventSource.subarray` attribute, e.g. to obtain the geometry for the telescope with id 1, use: - ``source.subarray.tel[1].camera.geometry``. - `~ctapipe.io.TableLoader` also has the ``.subarray`` attribute. + ``source.subarray.tel[1].camera.geometry``. The + `~ctapipe.io.TableLoader` instance also has the ``.subarray`` attribute. -* use the `CameraGeometry` constructor, where one has to specify all +* use the `~ctapipe.instrument.CameraGeometry` constructor, where one has to specify all necessary information (pixel positions, types, areas, etc) * load it from a pre-written file (which can be in any format - supported by ``astropy.table``, as long as that format allows for + supported by `astropy.table`, as long as that format allows for header-keywords as well as table entries. -Once loaded, the `CameraGeometry` object gives you access the pixel +Once loaded, the `~ctapipe.instrument.CameraGeometry` object gives you access the pixel positions, areas, neighbors, and shapes. -`CameraGeometry` is used by most image processing algorithms in the +`~ctapipe.instrument.CameraGeometry` is used by most image processing algorithms in the `ctapipe.image` module, as well as displays in the `ctapipe.visualization` module. Input/Output ------------ -You can write out a `CameraGeometry` by using the `CameraGeometry.to_table()` - method to turn it into an `astropy.table.Table`, and then call its `~astropy.table.Table.write` - function. Reading it back in can be done with `CameraGeometry.from_table()` +You can write out a `~ctapipe.instrument.CameraGeometry` by using the `CameraGeometry.to_table()` +method to turn it into an `astropy.table.Table`, and then call its `~astropy.table.Table.write` +function. Reading it back in can be done with `~ctapipe.instrument.CameraGeometry.from_table()` .. code-block:: python - geom = CameraGeometry(...) # constructed elsewhere + geom = ~ctapipe.instrument.CameraGeometry(...) # constructed elsewhere geom.to_table().write('mycam.fits.gz') # FITS output geom.to_table().write('mycam.h5', path='/cameras/mycam') # hdf5 output @@ -53,28 +53,28 @@ You can write out a `CameraGeometry` by using the `CameraGeometry.to_table()` # later read back in: - geom = CameraGeometry.from_table('mycam.ecsv', format='ascii.ecsv') - geom = CameraGeometry.from_table('mycam.fits.gz') - geom = CameraGeometry.from_table('mycam.h5', path='/cameras/mycam') + geom = ~ctapipe.instrument.CameraGeometry.from_table('mycam.ecsv', format='ascii.ecsv') + geom = ~ctapipe.instrument.CameraGeometry.from_table('mycam.fits.gz') + geom = ~ctapipe.instrument.CameraGeometry.from_table('mycam.h5', path='/cameras/mycam') A note on Pixel Neighbors ------------------------- -The `CameraGeometry` object provides two pixel-neighbor -representations: a *neighbor adjacency list* (in the ``neighbors`` -attribute) and a *pixel adjacency matrix* (in the ``neighbor_matrix`` +The `~ctapipe.instrument.CameraGeometry` object provides two pixel-neighbor +representations: a *neighbor adjacency list* (in the :attr:`~CameraGeometry.neighbors` +attribute) and a *pixel adjacency matrix* (in the :attr:`~CameraGeometry.neighbor_matrix` attribute). The former is a list of lists, where element *i* is a list of neighbors *j* of the *i*th pixel. The latter is a 2D matrix where row *i* is a boolean mask of pixels that are neighbors. It is not necessary to load or specify either of these neighbor -representations when constructing a `CameraGeometry`, since they +representations when constructing a `~ctapipe.instrument.CameraGeometry`, since they will be computed on-the-fly if left blank, using a KD-tree nearest-neighbor algorithm. It is recommended that all algorithms that need to be computationally -fast use the ``neighbor_matrix`` attribute, particularly in conjunction -with ``numpy`` operations, since it is quite speed-efficient. +fast use the :attr:`~CameraGeometry.neighbor_matrix` attribute, particularly in conjunction +with `numpy` operations, since it is quite speed-efficient. Examples -------- diff --git a/docs/ctapipe_api/instrument/camera_readout.rst b/docs/ctapipe_api/instrument/camera_readout.rst index b455257b5a1..d98cc235ddb 100644 --- a/docs/ctapipe_api/instrument/camera_readout.rst +++ b/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 diff --git a/docs/ctapipe_api/instrument/index.rst b/docs/ctapipe_api/instrument/index.rst index b3b98c040b1..3e2a53ebf36 100644 --- a/docs/ctapipe_api/instrument/index.rst +++ b/docs/ctapipe_api/instrument/index.rst @@ -6,10 +6,11 @@ Instrument (`~ctapipe.instrument`) .. currentmodule:: ctapipe.instrument + Introduction ============ -The `ctapipe.instrument` module contains classes and methods for +The `~ctapipe.instrument` module contains classes and methods for describing the instrumental layout and configuration. This module is under heavy restructuring and should not be considered diff --git a/docs/ctapipe_api/instrument/telescope.rst b/docs/ctapipe_api/instrument/telescope.rst index 8f77e29c258..e30b9364ead 100644 --- a/docs/ctapipe_api/instrument/telescope.rst +++ b/docs/ctapipe_api/instrument/telescope.rst @@ -14,3 +14,4 @@ Reference/API ------------- .. automodapi:: ctapipe.instrument.telescope + :no-inheritance-diagram: diff --git a/docs/ctapipe_logo.webp b/docs/ctapipe_logo.webp new file mode 100644 index 00000000000..bde5a0c7d4f Binary files /dev/null and b/docs/ctapipe_logo.webp differ diff --git a/docs/ctapipe_logo_dark.webp b/docs/ctapipe_logo_dark.webp new file mode 100644 index 00000000000..3c210e55e18 Binary files /dev/null and b/docs/ctapipe_logo_dark.webp differ diff --git a/docs/development/index.rst b/docs/development/index.rst index 856fdaa57ae..e214e31ad00 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -1,7 +1,7 @@ .. _guidelines: -Development Guidelines -====================== +Coding Guidelines +================= .. toctree:: diff --git a/docs/examples/Tools.ipynb b/docs/examples/Tools.ipynb index 6b541cc8495..02eb2b8f3c1 100644 --- a/docs/examples/Tools.ipynb +++ b/docs/examples/Tools.ipynb @@ -595,14 +595,22 @@ } ], "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, "language_info": { "codemirror_mode": { - "name": "ipython" + "name": "ipython", + "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", - "nbconvert_exporter": "python" + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.16" } }, "nbformat": 4, diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 07bad01c378..92e6ba6b614 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -1,3 +1,4 @@ + .. _getting_started: ****************************** @@ -77,7 +78,6 @@ Change to the directory where you cloned ``ctapipe``, and type: .. code-block:: console - $ conda env create -n cta-dev -f environment.yml @@ -238,11 +238,11 @@ You can do this at any time and more than once. It just moves the changes from your local branch on your development machine to your fork on github. -++++++++++++++++++++++++ -4. make a *Pull Request* -++++++++++++++++++++++++ +++++++++++++++++++++++++++ +4. Create a *Pull Request* +++++++++++++++++++++++++++ -When you're happy, you make PR on on your github fork page by clicking +When you're happy, you create PR on on your github fork page by clicking "pull request". You can also do this via *GitHub Desktop* if you have that installed, by pushing the pull-request button in the upper-right-hand corner. @@ -279,7 +279,7 @@ When the PR is accepted, the reviewer will merge your branch into the *master* repo on cta-observatory's account. +++++++++++++++++++++++++++++ -6. delete your feature branch +6. Delete your feature branch +++++++++++++++++++++++++++++ since it is no longer needed (assuming it was accepted and merged in): diff --git a/docs/index.rst b/docs/index.rst index def76c2a40d..84dec76af64 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,8 @@ .. include:: references.txt +:html_theme.sidebar_secondary.remove: true +:html_theme.sidebar_primary.remove: true + .. _ctapipe: ============================================== @@ -8,60 +11,174 @@ Prototype CTA Pipeline Framework (``ctapipe``) .. currentmodule:: ctapipe -**version**: |version| +| -.. image:: ctapipe_logo.png +.. image:: ctapipe_logo.webp + :class: only-light :align: center :width: 90% + :alt: The ctapipe logo. -What is ctapipe? -================ +.. image:: ctapipe_logo_dark.webp + :class: only-dark + :align: center + :width: 90% + :alt: The ctapipe logo. -``ctapipe`` is a framework for prototyping the low-level data processing algorithms for the Cherenkov Telescope Array. +| -.. CAUTION:: - This is not yet stable code, so expect large and rapid changes to - structure and functionality as we explore various design choices before - the 1.0 release. +**Date**: |today| **Version**: |version| -* Code, feature requests, bug reports, pull requests: https://github.com/cta-observatory/ctapipe -* Docs: https://ctapipe.readthedocs.io/ -* License: BSD-3 -* Python: |python_requires| +**Useful links**: +`Source Repository `__ | +`Issue Tracker `__ | +`Discussions `__ +**License**: BSD-3 **Python**: |python_requires| +| -.. _ctapipe_docs: +``ctapipe`` is a framework for prototyping the low-level data processing algorithms for the Cherenkov Telescope Array. -General documentation -===================== +.. _ctapipe_docs: .. toctree:: :maxdepth: 1 - :glob: + :hidden: - getting_started_users/index - getting_started/index + User Guide + Developer Guide development/index + ctapipe_api/index tutorials/index examples/index tools/index FAQ data_models/index - ctapipe_api/index bibliography changelog -Module API Status (relative to next release) -============================================ -ctapipe is under activate developement and we will make breaking changes from release to release until -we reach version 1.0. +.. grid:: 1 2 2 3 + + .. grid-item-card:: + + :octicon:`book;40px` + + User Guide + ^^^^^^^^^^ + + Learn how to get started as a user. This guide + will help you install ctapipe. + + +++ + + .. button-ref:: getting_started_users/index + :expand: + :color: primary + :click-parent: + + To the user guide + + + .. grid-item-card:: + + :octicon:`person-add;40px` + + Developer Guide + ^^^^^^^^^^^^^^^ + + Learn how to get started as a developer. + This guide will help you install ctapipe for development + and explains how to contribute. + + +++ + + .. button-ref:: getting_started/index + :expand: + :color: primary + :click-parent: + + To the developer guide + + + .. grid-item-card:: + + :octicon:`git-pull-request;40px` + + Coding Guidelines + ^^^^^^^^^^^^^^^^^ + + These guidelines explain the coding style and the workflow. The ctapipe + enhancement proposals (CEPs) can also be found here. + + +++ + + .. button-ref:: development/index + :expand: + :color: primary + :click-parent: + + To the development guidelines + + + .. grid-item-card:: + + :octicon:`code;40px` + + API Docs + ^^^^^^^^ + + The API docs contain detailed descriptions of + of the various modules and functions included + in ctapipe. + + +++ + + .. button-ref:: ctapipe_api/index + :expand: + :color: primary + :click-parent: + + To API docs + + + .. grid-item-card:: + + :octicon:`mortar-board;40px` + + Tutorials + ^^^^^^^^^ + + A collection of tutorials aimed at new users + and developers to familiarize with ctapipe. + + +++ + + .. button-ref:: tutorials/index + :expand: + :color: primary + :click-parent: + + To the tutorials + + + .. grid-item-card:: + + :octicon:`light-bulb;40px` + + Examples + ^^^^^^^^ + + Some lower-level examples of features included in the ctapipe API. + + +++ + + .. button-ref:: examples/index + :expand: + :color: primary + :click-parent: -Development Help -================ + To the examples -* Development workflow examples from AstroPy: https://astropy.readthedocs.org/en/latest/development/workflow/development_workflow.html -* GIT tutorial: https://www.atlassian.com/git/tutorials/syncing/git-pull -* Code distribution and Packaging https://packaging.python.org/en/latest/ diff --git a/environment.yml b/environment.yml index e2d90f14896..99abfdd296c 100644 --- a/environment.yml +++ b/environment.yml @@ -9,7 +9,7 @@ dependencies: - astropy=5 - black - bokeh=2 - - nbsphinx >=0.8.12,<0.9 + - nbsphinx - cython - graphviz - h5py @@ -34,9 +34,10 @@ dependencies: - scikit-learn - scipy - setuptools - - sphinx=3.5 + - sphinx - sphinx-automodapi - - sphinx_rtd_theme + - pydata-sphinx-theme + - sphinx-design - tomli - towncrier - tqdm @@ -47,5 +48,4 @@ dependencies: - zlib - zstandard - eventio>=1.9.1 - - jinja2=3.0 # for sphinx 3.5, remove when updating to 4.x - ffmpeg # for making movies in the documentation diff --git a/setup.cfg b/setup.cfg index 5092c8e6292..0858479d898 100644 --- a/setup.cfg +++ b/setup.cfg @@ -56,12 +56,12 @@ tests = docs = - sphinx ~=3.5 - jinja2 ~=3.0.2 # for sphinx 3.5, remove when upgrading sphinx - sphinx_rtd_theme + sphinx + pydata_sphinx_theme sphinx_automodapi - nbsphinx ~=0.8.12 - numpydoc ~=1.4.0 + nbsphinx + numpydoc + sphinx-design jupyter notebook graphviz
{key}