DOC: template for sphinx documentation (#146)

Add a template for the Sphinx documentation. This is a reasonably
comprehensive first draft, but we anticipate that all of the
documentation will be updated and polished for public consumption in a
future issue.

Closes: #116

.readthedocs.yml

@@ -3,11 +3,14 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
 
 mkdocs:
   configuration: mkdocs.yml
 
+sphinx:
+  configuration: docs/conf.py
+
 python:
   install:
     - method: pip

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+
+
+# -- Project information -----------------------------------------------------
+
+from importlib import metadata
+
+project = "heracles"
+author = "Euclid Science Ground Segment"
+version = metadata.version(project)
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "numpydoc",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.katex",
+    "matplotlib.sphinxext.plot_directive",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+}
+
+templates_path = ["_templates"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_logo = "_static/Heracles.jpg"

docs/index.rst

@@ -0,0 +1,16 @@
+
+***************************************************************
+*HERACLES* --- Harmonic-space statistics on the sphere
+***************************************************************
+
+.. image:: _static/Heracles.jpg
+
+=================
+Table of Contents
+=================
+.. toctree::
+   :maxdepth: 2
+
+   manual/index
+   user/index
+   reference/index

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.https://www.sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/manual/examples.rst

@@ -0,0 +1,6 @@
+Examples
+========
+
+The best way to get started with *Heracles* is to follow the GitHub example__.
+
+__ https://github.com/heracles-ec/heracles/blob/main/examples/example.ipynb

docs/manual/index.rst

@@ -0,0 +1,10 @@
+===============
+Software manual
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   Examples
+   releases

docs/manual/installation.rst

@@ -0,0 +1,18 @@
+Installation
+============
+
+Requirements
+------------
+
+*Heracles* is auto tested on Python versions 3.8 - 3.12.  For now there is no official release so we recommend developer installation only.
+
+
+Developer installation
+----------------------
+
+If you want to install *Heracles* for local development, clone the repository and
+install the package in editable mode::
+
+    $ pip install -e .
+
+This will automatically add Heracles modules to your python path so that you can import into you Python codes.

docs/manual/releases.rst

@@ -0,0 +1,6 @@
+Releases
+========
+
+You may check for releases here:
+
+https://github.com/heracles-ec/heracles/releases/

docs/reference/index.rst

@@ -0,0 +1,8 @@
+==================
+Function reference
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   twopoint

docs/reference/twopoint.rst

@@ -0,0 +1,5 @@
+==============================
+Example twopoint documentation
+==============================
+
+Documentation to be written 'by hand' without use of automodule

docs/user/how-heracles-works.rst

@@ -0,0 +1,4 @@
+
+How *Heracles* works
+====================
+Todo

docs/user/index.rst

@@ -0,0 +1,9 @@
+==========
+User guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   how-heracles-works
+   publications

docs/user/publications.rst

@@ -0,0 +1,4 @@
+Publications
+============
+
+Publications are coming - watch this space!

environment.yml

@@ -4,6 +4,7 @@ dependencies:
   - healpy
   - numba
   - numpy
+  - matplotlib
   - pip
   - pip:
       - convolvecl

pyproject.toml

@@ -35,13 +35,16 @@ dynamic = [
 license = "LGPL-3.0-or-later"
 name = "heracles"
 optional-dependencies = {all = [
+    "matplotlib",
     "rich",
 ], docs = [
-    "mkdocs",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-material",
-    "mkdocstrings[python]",
+    "furo",
+    "matplotlib",
+    "numpydoc",
+    "sphinx",
+    "sphinxcontrib-katex",
 ], test = [
+    "matplotlib",
     "pytest",
     "pytest-rerunfailures",
 ]}