Merge pull request cta-observatory#1686 from cta-observatory/sphinx_w…

…arnings_as_errors

Treat sphinx warnings as erros, fix deploy workflow name

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
           source .github/install.sh
           python --version
           pip install codecov pytest-cov
-          pip install --use-feature=2020-resolver -e .[all]
+          pip install -e .[all]
           pip freeze
 
       - name: Tests
@@ -61,11 +61,14 @@ jobs:
           docs-folder: "docs/"
           pre-build-command: |
             apt update --yes && apt install --yes git build-essential pandoc
-            pip install -U pip setuptools wheel
-            pip install --use-feature=2020-resolver -e .[docs]
+            pip install -U pip setuptools wheel sphinx
+            pip install -e .[docs]
             git describe --tags
             python -c 'import ctapipe; print(ctapipe.__version__)'
 
+          # treat warnings as errors, make sure links are working
+          build-command: make html SPHINXOPTS="-W --keep-going -n --color -w /tmp/sphinx-log"
+
       - name: Deploy to gihub pages
         # only run on push to master
         if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}

.github/workflows/deploy.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Deploy to PyPi
 
 on:
   push:

ctapipe/__init__.py

@@ -1,7 +1,8 @@
-# Licensed under a 3-clause BSD style license - see LICENSE.rst
 """
 ctapipe - CTA Python pipeline experimental version
+
+Licensed under a 3-clause BSD style license - see LICENSE.rst
 """
 from .version import __version__
 
-__all__ = ['__version__']
+__all__ = ["__version__"]

ctapipe/calib/__init__.py

@@ -2,4 +2,6 @@
 """
 Calibration
 """
-from .camera import *
+from .camera import CameraCalibrator, GainSelector
+
+__all__ = ["CameraCalibrator", "GainSelector"]

ctapipe/calib/camera/calibrator.py

@@ -228,7 +228,7 @@ def __call__(self, event):
         Parameters
         ----------
         event : container
-            A `ctapipe` event container
+            A `~ctapipe.containers.ArrayEventContainer` event container
         """
         # TODO: How to handle different calibrations depending on telid?
         tel = event.r1.tel or event.dl0.tel or event.dl1.tel

ctapipe/containers.py

@@ -47,6 +47,9 @@
     "TimingParametersContainer",
     "TriggerContainer",
     "WaveformCalibrationContainer",
+    "StatisticsContainer",
+    "IntensityStatisticsContainer",
+    "PeakTimeStatisticsContainer",
 ]
 
 

ctapipe/coordinates/camera_frame.py

@@ -19,6 +19,9 @@
 from .representation import PlanarRepresentation
 
 
+__all__ = ["CameraFrame"]
+
+
 class MirrorAttribute(Attribute):
     """A frame Attribute that can only store the integers 1 and 2"""
 
@@ -138,14 +141,10 @@ def camera_to_telescope(camera_coord, telescope_frame):
     # where theta is the angle to the optical axis and r is the distance
     # to the camera center in the focal plane
     fov_lat = u.Quantity(
-        (x_rotated / focal_length).to_value(u.dimensionless_unscaled),
-        u.rad,
-        copy=False,
+        (x_rotated / focal_length).to_value(u.dimensionless_unscaled), u.rad, copy=False
     )
     fov_lon = u.Quantity(
-        (y_rotated / focal_length).to_value(u.dimensionless_unscaled),
-        u.rad,
-        copy=False,
+        (y_rotated / focal_length).to_value(u.dimensionless_unscaled), u.rad, copy=False
     )
 
     representation = UnitSphericalRepresentation(lat=fov_lat, lon=fov_lon)

ctapipe/coordinates/nominal_frame.py

@@ -25,6 +25,8 @@
     AltAz,
 )
 
+__all__ = ["NominalFrame"]
+
 
 class NominalFrame(BaseCoordinateFrame):
     """

ctapipe/coordinates/representation.py

@@ -1,15 +1,15 @@
 """
 This module defines any reference systems which may be needed in addition
 """
-from astropy.coordinates import (
-    BaseRepresentation,
-    CartesianRepresentation,
-)
+from astropy.coordinates import BaseRepresentation, CartesianRepresentation
 import astropy.units as u
 from collections import OrderedDict
 from numpy import broadcast_arrays
 
 
+__all__ = ["PlanarRepresentation"]
+
+
 class PlanarRepresentation(BaseRepresentation):
     """
     Representation of a point in a 2D plane.

ctapipe/coordinates/telescope_frame.py

@@ -25,6 +25,8 @@
     AltAz,
 )
 
+__all__ = ["TelescopeFrame"]
+
 
 class TelescopeFrame(BaseCoordinateFrame):
     """

ctapipe/core/component.py

@@ -82,17 +82,17 @@ class Component(Configurable, metaclass=AbstractConfigurableMeta):
     Components are classes that are configurable via traitlets
     and setup a logger in the ctapipe logging hierarchy.
 
-    `traitlets` can validate values and provide defaults and
+    ``traitlets`` can validate values and provide defaults and
     descriptions. These will be automatically translated into
     configuration parameters (command-line, config file, etc). Note
     that any parameter that should be externally configurable must
-    have its `config` attribute set to `True`, e.g. defined like
-    `myparam = Integer(0, help='the parameter').tag(config=True)`.
+    have its ``config`` attribute set to ``True``, e.g. defined like
+    ``myparam = Integer(0, help='the parameter').tag(config=True)``.
 
-    All components also contain a `logger` instance in their `log`
+    All components also contain a ``Logger`` instance in their ``log``
     attribute, that you must use to output info, debugging data,
-    warnings, etc (do not use `print()` statements, instead use
-    `self.log.info()`, `self.log.warning()`, `self.log.debug()`, etc).
+    warnings, etc (do not use ``print()`` statements, instead use
+    ``self.log.info()``, ``self.log.warning()``, ``self.log.debug()``, etc).
 
     Components are generally used within `ctapipe.core.Tool`
     subclasses, which provide configuration handling and command-line
@@ -240,8 +240,9 @@ def _repr_html_(self):
 
 class TelescopeComponent(Component):
     """
-    A component that needs a SubarrayDescription to be constructed, and which
-    contains configurable `TelescopeParameters` that must be configured on construction.
+    A component that needs a `~ctapipe.instrument.SubarrayDescription` to be constructed,
+    and which contains configurable `~ctapipe.core.traits.TelescopeParameter` fields
+    that must be configured on construction.
     """
 
     def __init__(self, subarray, config=None, parent=None, **kwargs):

ctapipe/core/container.py

@@ -11,20 +11,22 @@
 
 log = logging.getLogger(__name__)
 
+__all__ = ["Container", "Field", "FieldValidationError", "Map"]
+
 
 class FieldValidationError(ValueError):
     pass
 
 
 class Field:
     """
-    Class for storing data in `Containers`.
+    Class for storing data in a `Container`.
 
     Parameters
     ----------
     default:
         default value of the item (this will be set when the `Container`
-        is constructed, as well as when  `Container.reset()` is called
+        is constructed, as well as when  ``Container.reset`` is called
     description: str
         Help text associated with the item
     unit: str or astropy.units.core.UnitBase
@@ -146,7 +148,7 @@ def __init__(self, default, description="", unit=None, ucd=None, reason=""):
 
 class ContainerMeta(type):
     """
-    The MetaClass for the Containers
+    The MetaClass for `Container`
 
     It reserves __slots__ for every class variable,
     that is of instance `Field` and sets all other class variables
@@ -190,11 +192,11 @@ class Container(metaclass=ContainerMeta):
     such as a description, defaults, and units for each item in the
     container.
 
-    Containers can transform the data into a `dict` using the `
-    Container.as_dict()` method.  This allows them to be written to an
+    Containers can transform the data into a `dict` using the
+    ``as_dict`` method.  This allows them to be written to an
     output table for example, where each Field defines a column. The
     `dict` conversion can be made recursively and even flattened so
-    that a nested set of `Containers` can be translated into a set of
+    that a nested set of `Containers <Container>`_ can be translated into a set of
     columns in a flat table without naming conflicts (the name of the
     parent Field is pre-pended).
 
@@ -211,19 +213,19 @@ class Container(metaclass=ContainerMeta):
     >>>    # metadata will become header keywords in an output file:
     >>>    cont.meta['KEY'] = value
 
-    `Field`s inside `Containers` can contain instances of other
-    `Containers`, to allow for a hierarchy of containers, and can also
+    `Fields <Field>`_ inside `Containers <Container>`_ can contain instances of other
+    containers, to allow for a hierarchy of containers, and can also
     contain a `Map` for the case where one wants e.g. a set of
-    sub-classes indexed by a value like the `telescope_id`. Examples
+    sub-classes indexed by a value like the ``telescope_id``. Examples
     of this can be found in `ctapipe.containers`
 
-    `Containers` work by shadowing all class variables (which must be
+    `Container` works by shadowing all class variables (which must be
     instances of `Field`) with instance variables of the same name the
-    hold the value expected. If `Container.reset()` is called, all
+    hold the value expected. If ``reset`` is called, all
     instance variables are reset to their default values as defined in
     the class.
 
-    Finally, `Containers` can have associated metadata via their
+    Finally, a Container can have associated metadata via its
     `meta` attribute, which is a `dict` of keywords to values.
 
     """
@@ -270,7 +272,7 @@ def values(self):
 
     def as_dict(self, recursive=False, flatten=False, add_prefix=False):
         """
-        convert the `Container` into a dictionary
+        Convert the `Container` into a dictionary
 
         Parameters
         ----------
@@ -306,7 +308,15 @@ def as_dict(self, recursive=False, flatten=False, add_prefix=False):
             return d
 
     def reset(self, recursive=True):
-        """ set all values back to their default values"""
+        """
+        Reset all values back to their default values
+
+        Parameters
+        ----------
+        recursive: bool
+            If true, also reset all sub-containers
+        """
+
         for name, value in self.fields.items():
             if isinstance(value, Container):
                 if recursive:
@@ -361,7 +371,7 @@ def validate(self):
 class Map(defaultdict):
     """A dictionary of sub-containers that can be added to a Container. This
     may be used e.g. to store a set of identical sub-Containers (e.g. indexed
-    by `tel_id` or algorithm name).
+    by ``tel_id`` or algorithm name).
     """
 
     def as_dict(self, recursive=False, flatten=False, add_prefix=False):
@@ -389,6 +399,7 @@ def as_dict(self, recursive=False, flatten=False, add_prefix=False):
             return d
 
     def reset(self, recursive=True):
+        """Calls all ``Container.reset`` for all values in the Map"""
         for val in self.values():
             if isinstance(val, Container):
                 val.reset(recursive=recursive)

ctapipe/core/provenance.py

@@ -61,9 +61,9 @@ class Provenance(metaclass=Singleton):
     """
     Manage the provenance info for a stack of *activities*
 
-    use `start_activity(name)` to start an activity. Any calls to
-    `add_input_entity()` or `add_output_entity()` will register files within
-    that activity. Finish the current activity with `finish_activity()`.
+    use `start_activity(name) <start_activity>`_ to start an activity. Any calls to
+    `add_input_file` or `add_output_file` will register files within
+    that activity. Finish the current activity with `finish_activity`.
 
     Nested activities are allowed, and handled as a stack. The final output
     is not hierarchical, but a flat list of activities (however hierarchical
@@ -166,7 +166,7 @@ def provenance(self):
 
     def as_json(self, **kwargs):
         """return all finished provenance as JSON.  Kwargs for `json.dumps`
-        may be included, e.g. `indent=4`"""
+        may be included, e.g. ``indent=4``"""
 
         def set_default(obj):
             """ handle sets (not part of JSON) by converting to list"""

ctapipe/core/tool.py

@@ -17,6 +17,9 @@
 from .logging import create_logging_config, ColoredFormatter, DEFAULT_LOGGING
 
 
+__all__ = ["Tool", "ToolConfigurationError"]
+
+
 class CollectTraitWarningsHandler(logging.NullHandler):
     regex = re.compile(".*Config option.*not recognized")
 
@@ -46,14 +49,14 @@ class Tool(Application):
 
     Tool developers should create sub-classes, and a name,
     description, usage examples should be added by defining the
-    `name`, `description` and `examples` class attributes as
-    strings. The `aliases` attribute can be set to cause a lower-level
-    `Component` parameter to become a high-level command-line
+    ``name``, ``description`` and ``examples`` class attributes as
+    strings. The ``aliases`` attribute can be set to cause a lower-level
+    `~ctapipe.core.Component` parameter to become a high-level command-line
     parameter (See example below). The `setup()`, `start()`, and
     `finish()` methods should be defined in the sub-class.
 
     Additionally, any `ctapipe.core.Component` used within the `Tool`
-    should have their class in a list in the `classes` attribute,
+    should have their class in a list in the ``classes`` attribute,
     which will automatically add their configuration parameters to the
     tool.
 
@@ -110,9 +113,9 @@ def main():
            main()
 
 
-    If this `main()` method is registered in `setup.py` under
+    If this ``main()`` function is registered in ``setup.py`` under
     *entry_points*, it will become a command-line tool (see examples
-    in the `ctapipe/tools` subdirectory).
+    in the ``ctapipe/tools`` subdirectory).
 
     """
 
@@ -233,7 +236,7 @@ def add_component(self, component_instance):
     @abstractmethod
     def setup(self):
         """set up the tool (override in subclass). Here the user should
-        construct all `Components` and open files, etc."""
+        construct all ``Components`` and open files, etc."""
         pass
 
     @abstractmethod