DOC: add stubs for documentation (#17)

Adds the infrastructure for building documentation. Can currently only
be built locally, as the repository is still private, but will
eventually be built on ReadTheDocs.

Closes: #4
Reviewed-by: Nicolas Tessore
Co-authored-by: Nicolas Tessore <[email protected]>

.github/workflows/test.yml

@@ -54,9 +54,3 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: pipx run build
-  # docs:
-  #   name: Docs
-  #   runs-on: ubuntu-latest
-  #   steps:
-  #   - uses: actions/checkout@v4
-  #   - run: pipx run --spec '.[docs]' sphinx-build -W -b html docs _build/html

.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -1,3 +1,8 @@
 # _Heracles_ — Harmonic-space statistics on the sphere
 
+[![PyPI](https://img.shields.io/pypi/v/heracles)](https://pypi.org/project/heracles)
+[![Python](https://img.shields.io/pypi/pyversions/heracles)](https://www.python.org)
+[![Documentation](https://readthedocs.org/projects/heracles/badge/?version=latest)](https://heracles.readthedocs.io/en/latest/?badge=latest)
+[![Test](https://github.com/heracles-ec/heracles/actions/workflows/test.yml/badge.svg)](https://github.com/heracles-ec/heracles/actions/workflows/test.yml)
+
 The _Heracles_ code was developed in the _Euclid_ Science Ground Segment.

docs/api.md

@@ -0,0 +1,3 @@
+# API Documentation
+
+::: heracles

docs/index.md

@@ -0,0 +1,3 @@
+{%
+   include-markdown "../README.md"
+%}

heracles/__init__.py

@@ -16,6 +16,7 @@
 #
 # You should have received a copy of the GNU Lesser General Public
 # License along with Heracles. If not, see <https://www.gnu.org/licenses/>.
+"""Main module of the *Heracles* package."""
 
 try:
     from ._version import __version__, __version_tuple__  # noqa: F401

heracles/maps.py

@@ -379,10 +379,9 @@ def mapper(page: "CatalogPage") -> None:
 
             _map_real(wht, val, ipix, w, v)
 
-            if page.size:
-                ngal += page.size
-                wmean += (w - wmean).sum() / ngal
-                var += ((w * v) ** 2 - var).sum() / ngal
+            ngal += page.size
+            wmean += (w - wmean).sum() / ngal
+            var += ((w * v) ** 2 - var).sum() / ngal
 
         # the mapper function is yield-ed to be applied over the catalogue
         yield mapper
@@ -531,10 +530,9 @@ def mapper(page: "CatalogPage") -> None:
 
             _map_complex(wht, val, ipix, w, re, im)
 
-            if page.size:
-                ngal += page.size
-                wmean += (w - wmean).sum() / ngal
-                var += ((w * re) ** 2 + (w * im) ** 2 - var).sum() / ngal
+            ngal += page.size
+            wmean += (w - wmean).sum() / ngal
+            var += ((w * re) ** 2 + (w * im) ** 2 - var).sum() / ngal
 
         # the mapper function is yield-ed to be applied over the catalogue
         yield mapper

mkdocs.yml

@@ -0,0 +1,46 @@
+site_name: Heracles
+site_url: https://heracles.readthedocs.io
+nav:
+  - Home: index.md
+  - API: api.md
+theme:
+  name: material
+  palette:
+    # palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+    # palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+plugins:
+  - include-markdown
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            # general
+            allow_inspection: false
+            show_bases: false
+            show_source: false
+            # headings
+            show_category_heading: true
+            show_object_full_path: false
+            show_root_toc_entry: true
+            # members
+            filters: ["!^__?"]
+            inherited_members: true
+            show_submodules: false
+            # docstrings
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: spacy
+            merge_init_into_class: true
+            show_if_no_docstring: true
+            # signatures
+            line_length: 80
+            show_signature: false
+  - search

pyproject.toml

@@ -14,6 +14,10 @@ classifiers = [
     "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
     "Topic :: Scientific/Engineering :: Astronomy",
 ]
 dependencies = [
@@ -30,11 +34,10 @@ dynamic = [
 license = "LGPL-3.0-or-later"
 name = "heracles"
 optional-dependencies = {docs = [
-    "furo",
-    "matplotlib",
-    "numpydoc",
-    "sphinx",
-    "sphinxcontrib-katex",
+    "mkdocs",
+    "mkdocs-include-markdown-plugin",
+    "mkdocs-material",
+    "mkdocstrings[python]",
 ], test = [
     "pytest",
     "pytest-rerunfailures",