Documentation (cta-observatory#143)

* Work on documentation, with user guide, developer guide, pretty welcome page * Ignore automatically built _autosummary sub-directory from Sphinx * Add default role to Sphinx configuration * Fix PyPI badge target * Add sphinx_design as requirement for doc * Fix ctapipe URL * Fix link to API doc from welcome page --------- Co-authored-by: Jean-Philippe Lenain <[email protected]>
ArmelleJB · Aug 1, 2024 · b70033f · b70033f
1 parent e4bef46
commit b70033f
Show file tree

Hide file tree

Showing 9 changed files with 290 additions and 105 deletions.
diff --git a/.gitignore b/.gitignore
@@ -22,7 +22,7 @@ htmlcov
 MANIFEST
 
 # Sphinx
-docs/api
+docs/_autosummary
 docs/_build
 
 # Eclipse editor project files

diff --git a/README.md b/README.md
@@ -1,110 +1,14 @@
-# nectarchain [![Build Status](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml?query=workflow%3ACI+branch%3Amain) [![pypi](https://badge.fury.io/py/nectarchain.svg)](https://badge.fury.io/py/nectarchain) [![conda](https://anaconda.org/conda-forge/nectarchain/badges/version.svg)](https://anaconda.org/conda-forge/nectarchain)
+# nectarchain [![Build Status](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cta-observatory/nectarchain/actions/workflows/ci.yml?query=workflow%3ACI+branch%3Amain) [![pypi](https://badge.fury.io/py/nectarchain.svg)](https://pypi.org/project/nectarchain) [![conda](https://anaconda.org/conda-forge/nectarchain/badges/version.svg)](https://anaconda.org/conda-forge/nectarchain) [![codecov](https://codecov.io/github/cta-observatory/nectarchain/graph/badge.svg?token=TDhZlJtbMv)](https://codecov.io/github/cta-observatory/nectarchain)
 
 Repository for the high level analysis of the NectarCAM data.
 The analysis is heavily based on [ctapipe](https://github.com/cta-observatory/ctapipe), adding custom code for NectarCAM calibration.
 
-## Installation
-
-`nectarchain` is available as a [PyPI](https://pypi.org/project/nectarchain/) or [`conda`](https://anaconda.org/conda-forge/nectarchain) package, or as a [Singularity](https://apptainer.org/news/community-announcement-20211130/)/[Apptainer](https://apptainer.org/) container.
-
-### Using conda/mamba
-
-`conda` is a package manager, distributed e.g. within [Anaconda](https://www.anaconda.com/products/distribution). Use of its re-implementation in C++, `mamba`, is strongly advised instead. `mamba` is shipped e.g. within [Mambaforge](https://mamba.readthedocs.io/en/latest/installation.html) which can advantageously replace Anaconda altogether (lighter and faster).
-
-```shell
-mamba create -n nectarchain -c conda-forge nectarchain
-```
-
-### Using pip
-
-`nectarchain` can also be manually installed as a PyPI package, albeit following specific requirements which are automatically accounted for through a `conda`/`mamba` installation.
-
-```shell
-mamba create -n nectarchain python=3.11
-mamba activate nectarchain
-pip install nectarchain
-```
-
-### As a container
-
-`nectarchain` is planned to be pushed on each release on the [GitHub Container Registry](ghcr.io) as an [Apptainer](https://apptainer.org/) image. Such a container can be instantiated with:
-
-```shell
-apptainer shell oras://ghcr.io/cta-observatory/nectarchain:latest
-```
-
-The `nectarchain` code is then available under `/opt/cta/nectarchain`.
-
-[DIRAC support](#optional-dirac-support) is fully available and configured within such a container.
-
-#### Note to macOS users
-
-macOS users may experience errors when trying to initialize a proxy to DIRAC when the [DIRAC support is enabled](#optional-dirac-support), especially with recent hardware equipped with M1 or M2 Apple CPU chips. The container alternative can then help having an environment with CTADIRAC fully configured. However, [Apptainer](https://apptainer.org/) is [not readily available on macOS](https://apptainer.org/docs/admin/main/installation.html#mac), but there is a workaround using [`lima` virtualization technology](https://lima-vm.io/) on a Mac.
-
-**TL;DR**
-
-```shell
-brew install qemu lima
-limactl start template://apptainer
-limactl shell apptainer apptainer run --bind $HOME:/home/$USER.linux oras://ghcr.io/cta-observatory/nectarchain:latest
-```
-
-If you are running a Mac which CPU is based on ARM architecture (M1 or M2 Apple chips), when starting the `apptainer` container (second line above), please select the `Open an editor to review or modify the current configuration` option and add the following line at the beginning of the configuration file:
-```shell
-arch: "x86_64"
-```
-otherwise, please proceed with the `Proceed with the current configuration` option.
-
-The mount point `/tmp/lima` is shared between the host machine and the `apptainer` container, and writable from both.
-
-### Manual installation (for developers)
-
-This is the recommended installation procedure for developers. `nectarchain` should be `pip`-installed in development (_aka_ editable) mode.
-
-```shell
-git clone https://github.com/cta-observatory/nectarchain.git
-cd nectarchain
-mamba env create --name nectarchain --file environment.yml
-mamba activate nectarchain
-pip install -e .
-```
-
-Enable [pre-commit hooks](https://pre-commit.com/), which enforces adherence to PEP8 coding style:
-
-```shell
-pre-commit install
-```
-
-Please follow the [same conventions as `ctapipe`](https://ctapipe.readthedocs.io/en/latest/getting_started/) regarding settings of Git remotes, and how to contribute to the code with pull requests.
-
-### Optional DIRAC support
-
-_Note_: this is **not** needed if you are using `nectarchain` [as a container](#as-a-container), as DIRAC is already fully installed and configured within.
-
-To enable support for DIRAC within the same environment, do the following after the installation of `nectarchain` described above:
-
-```shell
-mamba activate nectarchain 
-mamba install dirac-grid
-conda env config vars set X509_CERT_DIR=${CONDA_PREFIX}/etc/grid-security/certificates X509_VOMS_DIR=${CONDA_PREFIX}/etc/grid-security/vomsdir X509_VOMSES=${CONDA_PREFIX}/etc/grid-security/vomses
-# The following is needed for the environment variables, used for DIRAC configuration, to be available:
-mamba deactivate
-mamba activate nectarchain
-pip install CTADIRAC
-dirac-configure
-```
+`nectarchain` is currently pinned to `ctapipe` version 0.19.
 
-Some Mac OS users (running on M1 chip) may experience a `M2Crypto.SSL.SSLError` error when trying to initiate a DIRAC proxy with `dirac-proxy-init`. Instead of:
-```shell
-mamba install dirac-grid
-```
-one may try:
-```shell
-mamba install dirac-grid "voms=2.1.0rc2=h7a71a8a_7"
-```
-or the [container alternative](#note-to-macos-users) as explained above.
+This code is under rapid development. It is not recommended for production use unless you are an expert or developer!
 
-`nectarchain` is currently pinned to `ctapipe` version 0.19.
+* Code: https://github.com/cta-observatory/nectarchain
+* Docs: https://nectarchain.readthedocs.io/
 
 ## Contributing
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -48,6 +48,8 @@
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",  # Automatically document param types (less noise in
     # class signature)
+    "numpydoc",
+    "sphinx_design",
 ]
 
 autosummary_generate = True  # Turn on sphinx.ext.autosummary
@@ -71,6 +73,9 @@
 # The master toctree document.
 master_doc = "index"
 
+# have all links automatically associated with the right domain.
+default_role = "py:obj"
+
 templates_path = ["_templates"]
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -104,7 +109,9 @@
     ("py:class", "ClassesType"),
 ]
 
-suppress_warnings = ["autosummary"]
+suppress_warnings = [
+    "autosummary",
+]
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True

diff --git a/docs/developer-guide/getting-started.rst b/docs/developer-guide/getting-started.rst
@@ -3,6 +3,73 @@
 Getting Started For Developers
 ==============================
 
+We strongly recommend using the `mambaforge conda distribution <https://github.com/conda-forge/miniforge#mambaforge>`_.
+
+.. warning::
+
+   The following guide is used only if you want to *develop* the
+   ``nectarchain`` package, if you just want to write code that uses it
+   as a dependency, you can install ``nectarchain`` from PyPI or conda-forge.
+   See :ref:`getting_started_users`
+
+Installation
+------------
+
+This is the recommended installation procedure for developers. ``nectarchain`` should be ``pip``-installed in development (*aka* editable) mode.
+
+.. code-block:: console
+
+   $ git clone https://github.com/cta-observatory/nectarchain.git
+   $ cd nectarchain
+   $ mamba env create --name nectarchain --file environment.yml
+   $ mamba activate nectarchain
+   $ pip install -e .
+
+Enable `pre-commit hooks <https://pre-commit.com/>`_, which enforces adherence to PEP8 coding style:
+
+.. code-block:: console
+
+   $ pre-commit install
+
+Please follow the `same conventions as ctapipe <https://ctapipe.readthedocs.io/en/latest/developer-guide/index.html>`_ regarding settings of git remotes, and how to contribute to the code with pull requests.
+
+
+.. _optional-dirac-support:
+
+Optional DIRAC support
+----------------------
+
+*Note*: this is **not** needed if you are using ``nectarchain`` as a container :ref:`as-a-container`, as DIRAC is already fully installed and configured within.
+
+To enable support for DIRAC within the same environment, do the following after the installation of ``nectarchain`` described above:
+
+.. code-block:: console
+
+   $ mamba activate nectarchain
+   $ mamba install dirac-grid
+   $ conda env config vars set X509_CERT_DIR=${CONDA_PREFIX}/etc/grid-security/certificates X509_VOMS_DIR=${CONDA_PREFIX}/etc/grid-security/vomsdir X509_VOMSES=${CONDA_PREFIX}/etc/grid-security/vomses
+   $ # The following is needed for the environment variables, used for DIRAC configuration, to be available:
+   $ mamba deactivate
+   $ mamba activate nectarchain
+   $ pip install CTADIRAC
+   $ dirac-configure
+
+
+Some Mac OS users (running on M1 chip) may experience a ``M2Crypto.SSL.SSLError`` error when trying to initiate a DIRAC proxy with ``dirac-proxy-init``. Instead of:
+
+.. code-block:: console
+
+   $ mamba install dirac-grid
+
+one may try:
+
+.. code-block:: console
+
+  $ mamba install dirac-grid "voms=2.1.0rc2=h7a71a8a_7"
+
+or the container alternative as explained in  :ref:`troubleshooting`.
+
+
 Building the documentation
 --------------------------
 
@@ -16,4 +83,18 @@ The documentation can then be compiled with:
 
 .. code-block::
 
-    $ make -C docs html
+    $ make -C docs html
+
+Interactive Development Environment
+-----------------------------------
+
+It is recommended that a fully python-aware *interactive development
+environment* (IDE) is used to develop code, rather than a basic text
+editor. IDEs will automatically mark lines that have style
+problems. The recommended IDEs are:
+
+* `PyCharm CE <https://www.jetbrains.com/pycharm>`_ (Jetbrains)
+* `VS Code <https://code.visualstudio.com/>`_ (Microsoft)
+
+The IDEs provide a lot of support for avoiding common style and coding
+mistakes, and automatic re-formatting.
diff --git a/docs/index.rst b/docs/index.rst
@@ -5,18 +5,95 @@ Welcome to nectarchain's documentation!
 
 .. currentmodule:: nectarchain
 
-**version**:  |version| **Date**: |today|
+**Version**:  |version| **Date**: |today|
+
+**Useful links**:
+`Source Repository <https://github.com/cta-observatory/nectarchain>`__ |
+`Issue Tracker <https://github.com/cta-observatory/nectarchain/issues>`__ |
+`Discussions <https://github.com/cta-observatory/nectarchain/discussions>`__
+
+**License**: BSD-3
+
+**Python**: |python_requires|
+
+``nectarchain`` is intended for the high level analysis of the NectarCAM data. It is heavily based on `ctapipe <https://github.com/cta-observatory/ctapipe>`_, adding custom code for NectarCAM calibration.
 
 .. _nectarchain_docs:
 
 .. toctree::
     :maxdepth: 1
     :hidden:
 
+    user-guide/index
     developer-guide/index
     API reference <_autosummary/nectarchain>
 
 
+
+.. 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 nectarchain.
+
+        +++
+
+        .. button-ref:: user-guide/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 nectarchain for development
+        and explains how to contribute.
+
+        +++
+
+        .. button-ref:: developer-guide/index
+            :expand:
+            :color: primary
+            :click-parent:
+
+            To the developer guide
+
+
+    .. grid-item-card::
+
+        :octicon:`code;40px`
+
+        API Docs
+        ^^^^^^^^
+
+        The API docs contain detailed descriptions of
+        of the various modules, classes and functions
+        included in nectarchain.
+
+        +++
+
+        .. button-ref:: _autosummary/nectarchain
+            :expand:
+            :color: primary
+            :click-parent:
+
+            To the API docs
+
+
 Indices and tables
 ==================