gh-164: initial documentation for release (#176)

Add an initial draft of the documentation, to accompany the first public release of the software. Closes: #164
heracles-ec · Sep 1, 2024 · e5cfcc6 · e5cfcc6
1 parent b1e2acd
commit e5cfcc6
Show file tree

Hide file tree

Showing 26 changed files with 331 additions and 84 deletions.
diff --git a/README.md b/README.md
@@ -6,4 +6,30 @@
 [![Tests](https://github.com/heracles-ec/heracles/actions/workflows/tests.yml/badge.svg)](https://github.com/heracles-ec/heracles/actions/workflows/tests.yml)
 [![Coverage](https://coveralls.io/repos/github/heracles-ec/heracles/badge.svg?branch=main)](https://coveralls.io/github/heracles-ec/heracles?branch=main)
 
-The _Heracles_ code was developed in the _Euclid_ Science Ground Segment.
+This is _Heracles_, a code for harmonic-space statistics on the sphere.
+_Heracles_ can take catalogues of positions a function values on the sphere and
+turn them into wonderful things like angular power spectra and mixing matrices.
+
+To get started, read the [documentation](https://heracles.readthedocs.io).
+
+🛰️ **Made in the Euclid Science Ground Segment**
+
+## Installation (latest)
+
+To install the latest released version of the package:
+
+    pip install heracles
+
+You should do this in a dedicated environment (conda, venv, etc.)
+
+## Installation (git main)
+
+To install the latest unreleased version from the git main branch:
+
+    pip install git+https://github.com/heracles-ec/heracles.git
+
+## Installation (develop)
+
+Clone the repository, cd into the local copy, then install in editable mode:
+
+    pip install -e .
diff --git a/docs/api/catalog.rst b/docs/api/catalog.rst
@@ -0,0 +1,31 @@
+
+Catalogues
+==========
+
+.. currentmodule:: heracles
+
+
+The catalogue protocol
+----------------------
+
+.. autoclass:: Catalog
+
+.. autoclass:: CatalogBase
+
+.. autoclass:: CatalogPage
+
+
+Catalogue implementations
+-------------------------
+
+.. autoclass:: FitsCatalog
+
+.. autoclass:: ArrayCatalog
+
+
+Catalogue filters
+-----------------
+
+.. autoclass:: FootprintFilter
+
+.. autoclass:: InvalidValueFilter
diff --git a/docs/api/examples.rst b/docs/api/examples.rst
@@ -0,0 +1,14 @@
+Python examples
+===============
+
+The best way to get started with the Python interface for *Heracles* is to look
+at the example notebooks below.  If you want to follow along and run the
+examples yourself, the source files are found on in the repository__.
+
+__ https://github.com/heracles-ec/heracles/blob/main/examples
+
+
+.. toctree::
+   :maxdepth: 1
+
+   ../examples/example.ipynb
diff --git a/docs/api/fields.rst b/docs/api/fields.rst
@@ -0,0 +1,33 @@
+
+Fields
+======
+
+.. currentmodule:: heracles
+
+
+The field protocol
+------------------
+
+.. autoclass:: Field
+
+
+Mathematical fields
+-------------------
+
+.. autoclass:: ComplexField
+
+.. autoclass:: ScalarField
+
+.. autoclass:: Spin2Field
+
+
+Concrete fields
+---------------
+
+.. autoclass:: Positions
+
+.. autoclass:: Shears
+
+.. autoclass:: Visibility
+
+.. autoclass:: Weights
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -0,0 +1,34 @@
+
+Using *Heracles* from Python
+============================
+
+*Heracles* is a fully-featured library for harmonic-space statistics on the
+sphere.  The Python interface can be used, e.g., in exploratory work using
+Jupyter notebooks, or to create automated data processing pipelines for a large
+collaboration like *Euclid*.
+
+
+Importing *Heracles*
+--------------------
+
+To use *Heracles* from Python, it is usually enough to import its main module::
+
+    import heracles
+
+The ``heracles`` module contains most user-facing functionality.  However, some
+of *Heracles*' features require additional external dependencies; these
+features are therefore encapsulated in their own separate modules::
+
+    import heracles.healpy  # requires healpy
+    import heracles.ducc  # requires ducc0
+    import heracles.notebooks  # requires IPython, ipywidgets
+    import heracles.rich  # requires rich
+
+
+Python documentation
+--------------------
+
+The best way to get started with the Python interface for *Heracles* is to look
+at the provided :doc:`/api/examples`.
+
+The full list of user functionality is documented in the :doc:`/api/reference`.
diff --git a/docs/api/reference.rst b/docs/api/reference.rst
@@ -0,0 +1,19 @@
+
+Python API reference
+====================
+
+This is the API reference for using *Heracles* as a Python library.
+The documentation is broadly organized into the stages of a data processing
+pipeline.
+
+.. warning::
+
+   The API documentation is a work in progress.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   catalog
+   fields
+   twopoint
diff --git a/docs/api/twopoint.rst b/docs/api/twopoint.rst
@@ -0,0 +1,29 @@
+
+Two-point statistics
+====================
+
+.. currentmodule:: heracles
+
+
+Angular power spectra
+---------------------
+
+.. autofunction:: angular_power_spectra
+
+.. autofunction:: binned_cls
+
+.. autofunction:: debias_cls
+
+
+Mixing matrices
+---------------
+
+.. autofunction:: mixing_matrices
+
+.. autofunction:: binned_mms
+
+
+Auxiliary functions
+-------------------
+
+.. autofunction:: bin2pt
diff --git a/docs/cli/index.rst b/docs/cli/index.rst
@@ -0,0 +1,6 @@
+
+Using the *Heracles* CLI
+========================
+
+The *Heracles* CLI is functional but currently still unsupported.  It will be
+fully supported as part of the next *Heracles* release.
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,7 +16,7 @@
 
 from importlib import metadata
 
-project = "heracles"
+project = "Heracles"
 copyright = "2023-2024 Euclid Science Ground Segment"
 author = "Euclid Science Ground Segment"
 version = metadata.version(project)
@@ -28,10 +28,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "numpydoc",
+    "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinxcontrib.katex",
     "matplotlib.sphinxext.plot_directive",
+    "nbsphinx",
 ]
 
 intersphinx_mapping = {
@@ -55,3 +56,9 @@
 html_static_path = ["_static"]
 
 html_logo = "_static/logo.png"
+
+
+# -- Options for autodoc -----------------------------------------------------
+
+# This value controls how to represent typehints.
+autodoc_typehints = "description"
diff --git a/docs/examples b/docs/examples
@@ -0,0 +1 @@
+../examples
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -0,0 +1,61 @@
+Getting started
+===============
+
+These are the first steps to get up and running with *Heracles*.  First,
+install the *Heracles* package for Python using one of the methods described
+below.  Then, see the documentation on :doc:`/api/index` or :doc:`/cli/index`.
+
+
+Installing a release
+--------------------
+
+This is the usual way of installing *Heracles*, and should be your first port
+of call.
+
+The *Heracles* package requires Python 3.9+ and a number of dependencies.  It
+can be installed using `pip` in the usual manner:
+
+.. code-block:: console
+
+   $ pip install heracles
+
+This will also install any missing dependencies.
+
+.. note::
+
+   As usual, it is recommended to install *Heracles* into a dedicated
+   environment (conda, venv, etc.).
+
+For alternative ways to install the package, see `Installing from the
+repository`_ and `Developer installation`_.
+
+
+Installing from the repository
+------------------------------
+
+To install the latest work-in-progress version, install directly from the main
+branch of the git repository:
+
+.. code-block:: console
+
+   $ pip install git+https://github.com/heracles-ec/heracles.git
+
+This will install *Heracles* with a local version string that encodes the last
+release and any subsequent commits.
+
+
+Developer installation
+----------------------
+
+If you want to install *Heracles* for local development, clone the repository
+and install the package in editable mode:
+
+.. code-block:: console
+
+   $ # clone the repository
+   $ cd heracles
+   $ pip install -e .
+
+The result is similar to `Installing from the repository`_, but uses the local
+copy of the repository as the package source.  This means changes to your local
+files are applied without needing to reinstall the package.
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,17 +1,43 @@
 
-******************************************************
 *Heracles* --- Harmonic-space statistics on the sphere
-******************************************************
+======================================================
 
 .. image:: _static/logo.png
    :width: 50%
 
-=================
+This is *Heracles*, a code for harmonic-space statistics on the sphere.
+*Heracles* can take catalogues of positions a function values on the sphere and
+turn them into wonderful things like angular power spectra and mixing matrices.
+
+*Heracles* is both a Python library, to be used in notebooks or data processing
+pipelines, and a tool for running measurements from the command line using a
+configuration file.  To jump right in, see :doc:`/getting-started`,
+:doc:`api/index`, and :doc:`/cli/index`.
+
+🛰️ **Made in the Euclid Science Ground Segment**
+
+
 Table of Contents
-=================
+-----------------
+
+.. toctree::
+   :caption: Heracles
+   :maxdepth: 2
+
+   getting-started
+   publications
+   releases
+
+.. toctree::
+   :caption: Python interface
+   :maxdepth: 2
+
+   api/index
+   api/examples
+   api/reference
+
 .. toctree::
+   :caption: Command Line Interface
    :maxdepth: 2
 
-   manual/index
-   user/index
-   reference/index
+   cli/index
diff --git a/docs/manual/examples.rst b/docs/manual/examples.rst
diff --git a/docs/manual/index.rst b/docs/manual/index.rst
diff --git a/docs/manual/installation.rst b/docs/manual/installation.rst
diff --git a/docs/manual/releases.rst b/docs/manual/releases.rst