Update docs

docs/conf.py

@@ -128,16 +128,6 @@ 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:

docs/ctapipe_api/calib/index.rst

@@ -1,8 +1,12 @@
 .. _calib:
 
-===============================
- Calibration (`~ctapipe.calib`)
-===============================
+.. temporary worakaround to at least have calib in the title,
+   the reason is the usage of autosummary in the Reference/API
+   section below
+
+========================================
+Calibration (``calib``)
+========================================
 
 .. currentmodule:: ctapipe.calib
 
@@ -44,6 +48,19 @@ Submodules
 Reference/API
 =============
 
-.. automodapi:: ctapipe.calib
-    :no-inheritance-diagram:
-    :noindex:
+.. What follows is a *temporary* workaround to circumvent
+   various warnings of duplicate references caused by
+   calling automodapi on the camera package.
+
+ctapipe.calib Package
+---------------------
+
+Calibration
+
+.. raw:: html
+
+    <h3>Classes</h3>
+
+.. autosummary::
+    ~camera.CameraCalibrator
+    ~camera.GainSelector

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 `~CameraDescription` contains classes holding information about the
+Cherenkov camera, namely the `~CameraGeometry` and `~CameraReadout` classes.
 
 
 .. toctree::
@@ -17,12 +17,28 @@ Cherenkov camera, namely the `CameraGeometry` and `CameraReadout` classes.
 
 
 Reference/API
--------------
+=============
 
+.. What follows is a temporary workaround to circumvent
+   various warnings of duplicate references caused by
+   calling automodapi on the camera package.
+
+ctapipe.instrument.camera Package
+---------------------------------
+
+.. raw:: html
+
+    <h3>Classes</h3>
+
+
+.. autosummary::
+
+    ~CameraDescription
+    ~CameraGeometry
+    ~PixelShape
+    ~camera.geometry.UnknownPixelShapeWarning
+    ~CameraReadout
 
-.. automodapi:: ctapipe.instrument.camera
-    :no-inheritance-diagram:
 
 .. automodapi:: ctapipe.instrument.camera.description
     :no-inheritance-diagram:
-    :noindex:

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,67 +14,67 @@ 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
    geom.to_table().write('mycam.ecsv', format='ascii.ecsv') # text 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
 --------
@@ -92,4 +92,3 @@ Reference/API
 
 .. automodapi:: ctapipe.instrument.camera.geometry
     :no-inheritance-diagram:
-    :noindex:

docs/ctapipe_api/instrument/camera_readout.rst

@@ -55,4 +55,3 @@ Reference/API
 
 .. automodapi:: ctapipe.instrument.camera.readout
     :no-inheritance-diagram:
-    :noindex:

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

docs/ctapipe_api/instrument/telescope.rst

@@ -14,3 +14,4 @@ Reference/API
 -------------
 
 .. automodapi:: ctapipe.instrument.telescope
+    :no-inheritance-diagram: