Merge pull request #2536 from cta-observatory/fix_docs

Fix docs build, use sphinxcontrib-bibtex for bibliography

.codespell-ignores

@@ -1,3 +1,4 @@
 chec
 usera
 nd
+studi

docs/bibliography.rst

@@ -2,38 +2,5 @@
 References
 **********
 
-.. [chaudhuri93] B. B. Chaudhuri und P. Kundu. "Optimum circular fit
-    to weighted data in multi-dimensional space". Pattern
-    Recognition Letters 14.1 (1993), S. 1–6
 
-.. [chalmecalvet2013] R. Chalme-Calvet, M. de Naurois, J.-P. Tavernet
-    "Muon efficiency of the H.E.S.S" telescope. AtmoHEAD Workshop, 2013.
-    https://arxiv.org/pdf/1403.4550.pdf
-
-.. [denaurois2009] M de Naurois, L. Roland
-    "A high performance likelihood reconstruction of gamma-rays for imaging
-    atmospheric Cherenkov telescopes". Astroparticle Physics 32.5, (2009)
-    https://arxiv.org/abs/0907.2610
-
-.. [temme2016] Temme T.F., "On the hunt for photons: analysis of Crab Nebula
-    data obtainedby the first G-APD Cherenkov telescope" 2016
-    DOI: 10.17877/DE290R-17773
-
-.. [factcleaning] https://github.com/fact-project/fact-tools
-
-.. [ctatopleveldatamodel] K. Kosack et al, "Top-level Data Model", CTAO Computing
-    Department Internal Documentation, CTA-SPE-OSO-000000-0001, v1A.
-
-.. [gasparetto] Gasparetto T., "Development of a computing farm for Cloud
-    computing on GPU Development and optimisation of data-analysis
-    methodologies for the Cherenkov Telescope Array",
-    Ph.D. thesis, Academic Year 2018/2019.
-
-.. [lts_regression] P. J. Rousseeuw, K. van Driessen, "Computing LTS Regression for Large Data Sets",
-    Data Mining and Knowledge Discovery, 12, 29-45, DOI: 10.1007/s10618-005-0024-4
-
-.. [hillas_uncertainties] W. Wittek, "Image Parameters", MAGIC-TDAS internal note 02-03, (2002).
-
-.. [cta_sb_ob] Oya et al, Scheduling Block Data Model Specification, CTA-SPE-COM-000000-0003, Issue 1, Rev. c
-
-.. [cta_r1event] CTA R1/Event Data Model Specification, version 1 revision C (2022).
+.. bibliography::

docs/conf.py

@@ -53,6 +53,7 @@
     "sphinx.ext.mathjax",
     "sphinx_automodapi.automodapi",
     "sphinx_automodapi.smart_resolver",
+    "sphinxcontrib.bibtex",
     "nbsphinx",
     "matplotlib.sphinxext.plot_directive",
     "numpydoc",
@@ -399,3 +400,10 @@ def setup(app):
     "iminuit": ("https://scikit-hep.org/iminuit/", None),
     "traitlets": ("https://traitlets.readthedocs.io/en/stable/", None),
 }
+
+
+# workaround for sphinx-gallery-conf not being cacheable and warning resulting in docs failure
+suppress_warnings = ["config.cache"]
+
+bibtex_bibfiles = ["references.bib"]
+bibtex_encoding = "utf8"

docs/references.bib

@@ -0,0 +1,138 @@
+@article{chaudhuri93,
+  title={Optimum circular fit to weighted data in multi-dimensional space},
+  author={Chaudhuri, B. B. and Kundu, P.},
+  journal={Pattern Recognition Letters},
+  volume={14},
+  number={1},
+  pages={1--6},
+  year={1993},
+  doi={10.1016/0167-8655(93)90126-X},
+}
+
+@inproceedings{chalmecalvet2013,
+  title={Muon efficiency of the H.E.S.S. telescope},
+  author={Chalme-Calvet, R. and de Naurois, M. and Tavernet, J.-P.},
+  booktitle={Proceedings, Atmospheric Monitoring for High-Energy Astroparticle Detectors (AtmoHEAD)},
+  location={Saclay, France},
+  year={2013},
+  eprint={1403.4550},
+  archivePrefix={arXiv},
+  primaryClass={astro-ph.IM},
+}
+
+@article{denaurois2009,
+  title={A high performance likelihood reconstruction of gamma rays for imaging atmospheric Cherenkov telescopes},
+  author={De Naurois, M. and Rolland, L.},
+  journal={Astroparticle Physics},
+  volume={32},
+  number={5},
+  pages={231--252},
+  year={2009},
+  doi={10.1016/j.astropartphys.2009.09.001},
+}
+
+@phdthesis{phd-temme,
+  title={On the hunt for photons: analysis of Crab Nebula data obtained by the first G-APD Cherenkov telescope},
+  doi={10.17877/DE290R-17773},
+  author={Temme, Thomas Fabian},
+  school={TU Dortmund},
+  year={2016},
+}
+
+
+@misc{fact-tools,
+  title={FACT-Tools},
+  author={Brügge, K. and Nöthe, M. and Buß, J. and others},
+  url={https://github.com/fact-project/fact-tools},
+  year=2019,
+  version={v1.1.3},
+  doi={10.5281/zenodo.3529353},
+}%
+}
+
+
+@manual{ctao-top-level-data-model,
+  title={CTA Top-level Data Model Specification},
+  date={2022-04-30},
+  version={1b},
+  number={CTA-SPE-OSO-000000-0001},
+  organization={CTAO},
+  url={https://redmine.cta-observatory.org/dmsf/files/16325},
+}
+
+@phdthesis{phd-gasparetto,
+  author={Gasparetto, T.},
+  title={Development of a computing farm for Cloud computing on GPU - Development and optimisation of data-analysis methodologies for the Cherenkov Telescope Array},
+  year={2020},
+  school={Università degli Studi di Trieste},
+  url={https://arts.units.it/handle/11368/2963769},
+}
+
+@article{lts-regression,
+  title={Computing LTS regression for large data sets},
+  author={Rousseeuw, P. J. and Van Driessen, K.},
+  journal={Data mining and knowledge discovery},
+  volume={12},
+  pages={29--45},
+  year={2006},
+  doi={10.1007/s10618-005-0024-4},
+}
+
+%
+@techreport{hillas-uncertainties,
+  title={Image Parameters},
+  author={M. Wittek},
+  organization={MAGIC},
+  number={TDAS-02-03},
+  year={2002},
+  note={MAGIC internal note},
+}
+
+@manual{cta-sb-ob-data-model,
+  title={Scheduling Block Data Model Specification},
+  date={2022-12-20},
+  version={1e},
+  number={CTA-SPE-COM-000000-0003},
+  organization={CTAO},
+  url={https://redmine.cta-observatory.org/dmsf/files/15587},
+}
+
+@manual{ctao-r1-event-data-model,
+  title={CTAO R1/Event Data Model Specification},
+  date={2023-08-10},
+  version={2a},
+  number={CTA-SPE-COM-000000-0002},
+  organization={CTAO},
+  url={https://redmine.cta-observatory.org/dmsf/files/8627},
+}
+
+@article{muon-review,
+  title={Using muon rings for the calibration of the Cherenkov telescope array: a systematic review of the method and its potential accuracy},
+  author={Gaug, M. and Fegan, S. and Mitchell, A. M. W. and Maccarone, M. and Mineo, T. and Okumura, A.},
+  journal={The Astrophysical Journal Supplement Series},
+  volume={243},
+  number={1},
+  pages={11},
+  year={2019},
+  doi={10.3847/1538-4365/ab2123},
+}
+
+@article{hofmann-1999-comparison,
+  title={Comparison of techniques to reconstruct VHE gamma-ray showers from multiple stereoscopic Cherenkov images},
+  author={Hofmann, W. and Jung, I. and Konopelko, A. and Krawczynski, H. and Lampeitl, H. and Pühlhofer, G.},
+  journal={Astroparticle Physics},
+  volume={12},
+  number={3},
+  pages={135--143},
+  year={1999},
+  doi={10.1016/S0927-6505(99)00084-5},
+}
+
+
+@article{bright-star-catalog,
+  title={The Bright star catalogue},
+  author={Hoffleit, D. and Jaschek, C.},
+  journal={New Haven},
+  year={1991},
+  url={https://heasarc.gsfc.nasa.gov/W3Browse/star-catalog/bsc5p.html},
+}

environment.yml

@@ -39,6 +39,7 @@ dependencies:
   - sphinx-automodapi
   - pydata-sphinx-theme
   - sphinx-design
+  - sphinxcontrib-bibtex
   - tomli
   - towncrier
   - tqdm

examples/core/table_writer_reader.py

@@ -230,6 +230,11 @@ def create_stream(n_event):
 
 table.attrs
 
+######################################################################
+# close the file
+#
+h5.close()
+
 
 ######################################################################
 # Reading one-row-at-a-time:

pyproject.toml

@@ -69,6 +69,7 @@ docs = [
     "numpydoc",
     "sphinx-design",
     "sphinx-gallery",
+    "sphinxcontrib-bibtex",
     "jupyter",
     "notebook",
     "graphviz",

src/ctapipe/containers.py

@@ -142,7 +142,7 @@ class CoordinateFrameType(enum.Enum):
 
 
 class EventType(enum.Enum):
-    """Enum of EventTypes as defined in the CTA Data Model [cta_r1event]_"""
+    """Enum of EventTypes as defined in :cite:p:`ctao-r1-event-data-model`"""
 
     # calibrations are 0-15
     FLATFIELD = 0
@@ -1424,13 +1424,14 @@ class ArrayEventContainer(Container):
 
 
 class SchedulingBlockContainer(Container):
-    """Stores information about the scheduling block. This is a simplified
-    version of the SB model, only storing what is necessary for analysis. From
-    [cta_sb_ob]_
+    """Stores information about the scheduling block.
 
+    This is a simplified version of the SB model, only storing what is necessary for analysis.
+    From :cite:p:`cta-sb-ob-data-model`.
     """
 
     default_prefix = ""
+
     sb_id = Field(UNKNOWN_ID, "Scheduling block ID", type=np.uint64)
     sb_type = Field(
         SchedulingBlockType.UNKNOWN,

src/ctapipe/image/cleaning.py

@@ -333,8 +333,7 @@ def fact_image_cleaning(
 
     References
     ----------
-    See  [temme2016]_ and for implementation [factcleaning]_
-
+    See :cite:p:`phd-temme` and for implementation :cite:p:`fact-tools`.
     """
 
     # Step 1

src/ctapipe/image/muon/fitting.py

@@ -12,7 +12,7 @@ def kundu_chaudhuri_circle_fit(x, y, weights):
     Fast and reliable analytical circle fitting method previously used
     in the H.E.S.S. experiment for muon identification
 
-    Implementation based on [chaudhuri93]_
+    Implementation based on :cite:p:`chaudhuri93`
 
     Parameters
     ----------

src/ctapipe/image/muon/intensity_fitter.py

@@ -239,11 +239,8 @@ def image_prediction_no_units(
     min_lambda_m=300e-9,
     max_lambda_m=600e-9,
 ):
-    """Function for producing the expected image for a given set of trial
-    muon parameters without using astropy units but expecting the input to
-    be in the correct ones.
-
-    See [chalmecalvet2013]_
+    """
+    Unit-less version of `image_prediction`.
     """
 
     # First produce angular position of each pixel w.r.t muon center
@@ -431,6 +428,18 @@ def create_initial_guess(center_x, center_y, radius, telescope_description):
 
 
 class MuonIntensityFitter(TelescopeComponent):
+    """
+    Fit muon ring images with a theoretical model to estimate optical efficiency.
+
+    Function for producing the expected image for a given set of trial
+    muon parameters without using astropy units but expecting the input to
+    be in the correct ones.
+
+    The image prediction function is currently modeled after :cite:p:`chalmecalvet2013`.
+
+    For more information, also see :cite:p:`muon-review`.
+    """
+
     spe_width = FloatTelescopeParameter(
         help="Width of a single photo electron distribution", default_value=0.5
     ).tag(config=True)

src/ctapipe/image/pixel_likelihood.py

@@ -1,7 +1,7 @@
 """
 Class for calculation of likelihood of a pixel expectation, given the pixel amplitude,
 the level of noise in the pixel and the photoelectron resolution.
-This calculation is taken from [denaurois2009]_.
+This calculation is taken from :cite:p:`denaurois2009`.
 
 The likelihood is essentially a poissonian convolved with a gaussian, at low signal
 a full possonian approach must be adopted, which requires the sum of contributions
@@ -52,7 +52,7 @@ class PixelLikelihoodError(RuntimeError):
 def neg_log_likelihood_approx(image, prediction, spe_width, pedestal):
     """Calculate negative log likelihood for telescope.
 
-    Gaussian approximation from [denaurois2009]_, p. 22 (equation between (24) and (25)).
+    Gaussian approximation from :cite:p:`denaurois2009`, p. 22 (equation between (24) and (25)).
 
     Simplification:
 
@@ -105,7 +105,7 @@ def neg_log_likelihood_numeric(
 ):
     """
     Calculate likelihood of prediction given the measured signal,
-    full numerical integration from [denaurois2009]_.
+    full numerical integration from :cite:p:`denaurois2009`.
 
     Parameters
     ----------

src/ctapipe/io/metadata.py

@@ -1,11 +1,11 @@
 """
-Management of CTA Reference Metadata, as defined in the CTA Top-Level Data Model
-document [ctatopleveldatamodel]_ , version 1A. This information is required to be
-attached to the header of any
-files generated.
+Management of CTA Reference Metadata.
+
+Definitions from :cite:`ctao-top-level-data-model`.
+This information is required to be attached to the header of any files generated.
 
 The class Reference collects all required reference metadata, and can be turned into a
-flat dictionary.  The user should try to fill out all fields, or use a helper to fill
+flat dictionary. The user should try to fill out all fields, or use a helper to fill
 them (as in `Activity.from_provenance()`)
 
 .. code-block:: python

src/ctapipe/reco/hillas_intersection.py

@@ -71,7 +71,7 @@ def _far_outside_fov(fov_lat, fov_lon):
 class HillasIntersection(HillasGeometryReconstructor):
     """
     This class is a simple re-implementation of Hillas parameter based event
-    reconstruction. e.g. https://arxiv.org/abs/astro-ph/0607333
+    reconstruction. See algorithm I of :cite:p:`hofmann-1999-comparison`.
 
     In this case the Hillas parameters are all constructed in the shared
     angular (Nominal) system. Direction reconstruction is performed by
@@ -80,14 +80,12 @@ class HillasIntersection(HillasGeometryReconstructor):
     reconstruction is performed by performing the same procedure in the
     tilted ground system.
 
-    The height of maximum is reconstructed by the projection os the image
+    The height of maximum is reconstructed by the projection of the image
     centroid onto the shower axis, taking the weighted average of all images.
 
     Uncertainties on the positions are provided by taking the spread of the
     crossing points, however this means that no uncertainty can be provided
     for multiplicity 2 events.
-
-    Note: only input from CameraFrame is currently supported
     """
 
     atmosphere_profile_name = traits.CaselessStrEnum(