Extend documentation

.gitignore

@@ -71,6 +71,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/build/
+_build*
 
 # PyBuilder
 .pybuilder/
@@ -151,3 +152,5 @@ scratch_nbs/
 _devlog/
 tests/output
 .devcontainer/
+docs/generated
+scoringrules/vendored

.pre-commit-config.yaml

@@ -26,8 +26,8 @@ repos:
     hooks:
     - id: codespell
 
-  - repo: https://github.com/frazane/check-latex-math
-    rev: v0.2.2
-    hooks:
-      - id: latex-math-validation
-        args: ["scoringrules/", "docs/", "*.py", "*.md"]
+  #- repo: https://github.com/frazane/check-latex-math
+  #  rev: v0.2.2
+  #  hooks:
+  #    - id: latex-math-validation
+  #      args: ["scoringrules/", "docs/", "*.py", "*.md"]

.readthedocs.yaml

@@ -10,13 +10,13 @@ build:
   tools:
     python: "3.13"
 
-# Build documentation with Mkdocs
-mkdocs:
-   configuration: mkdocs.yaml
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
 
 # Optionally, but recommended,
 # declare the Python requirements required to build your documentation
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+python:
+   install:
+   - requirements: docs/requirements.txt

README.md

@@ -1,21 +1,38 @@
+<!-- centered images -->
 <p align="center">
-  <img src="docs/assets/images/banner_light.svg#gh-light-mode-only" />
-  <img src="docs/assets/images/banner_dark.svg#gh-dark-mode-only" />
+  <img src="docs/_static/banner_dark_long.svg#gh-dark-mode-only" alt="dark banner">
+  <img src="docs/_static/banner_light_long.svg#gh-light-mode-only" alt="light banner">
 </p>
 
-<br>
+# Probabilistic forecast evaluation
 
 [![CI](https://github.com/frazane/scoringrules/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/frazane/scoringrules/actions/workflows/ci.yaml)
 [![codecov](https://codecov.io/github/frazane/scoringrules/graph/badge.svg?token=J194X4HEBH)](https://codecov.io/github/frazane/scoringrules)
 [![pypi](https://img.shields.io/pypi/v/scoringrules.svg?colorB=<brightgreen>)](https://pypi.python.org/pypi/scoringrules/)
 
-Scoringrules is a python library for evaluating probabilistic forecasts by computing
-scoring rules and other diagnostic quantities. It aims to assist forecasting practitioners by
-providing a set of tools based the scientific literature and via its didactic approach.
+`scoringrules` is a python library that provides scoring rules to evaluate probabilistic forecasts.
+It's original goal was to reproduce the functionality of the R package
+[`scoringRules`](https://cran.r-project.org/web/packages/scoringRules/index.html) in python,
+thereby allowing forecasting practitioners working in python to enjoy the same tools as those
+working in R. The methods implemented in `scoringrules` are therefore based around those
+available in `scoringRules`, which are rooted in the scientific literature on probabilistic forecasting.
+
+The scoring rules available in `scoringrules` include, but are not limited to, the
+- Brier Score
+- Logarithmic Score
+- (Discrete) Ranked Probability Score
+- Continuous Ranked Probability Score (CRPS)
+- Dawid-Sebastiani Score
+- Energy Score
+- Variogram Score
+- Gaussian Kernel Score
+- Threshold-Weighted CRPS
+- Threshold-Weighted Energy Score
+
 
 ## Features
 
-- **Fast** computations of several probabilistic univariate and multivariate verification metrics
+- **Fast** computation of several probabilistic univariate and multivariate verification metrics
 - **Multiple backends**: support for numpy (accelerated with numba), jax, pytorch and tensorflow
 - **Didactic approach** to probabilistic forecast evaluation through clear code and documentation
 
@@ -28,7 +45,7 @@ pip install scoringrules
 
 ## Documentation
 
-Learn more about scoringrules in its official documentation at https://frazane.github.io/scoringrules/.
+Learn more about `scoringrules` in its official documentation at https://scoringrules.readthedocs.io/en/latest/.
 
 
 ## Quick example
@@ -41,26 +58,22 @@ fct = obs[:,None] + np.random.randn(100, 21) * 0.1
 sr.crps_ensemble(obs, fct)
 ```
 
-## Metrics
-- Brier Score
-- Continuous Ranked Probability Score (CRPS)
-- Logarithmic score
-- Error Spread Score
-- Energy Score
-- Variogram Score
-
-
 ## Citation
-If you found this library useful for your own research, consider citing:
+If you found this library useful, consider citing:
 
 ```
 @software{zanetta_scoringrules_2024,
   author = {Francesco Zanetta and Sam Allen},
-  title = {Scoringrules: a python library for probabilistic forecast evaluation},
+  title = {scoringrules: a python library for probabilistic forecast evaluation},
   year = {2024},
   url = {https://github.com/frazane/scoringrules}
 }
 ```
 
 ## Acknowledgements
-[scoringRules](https://cran.r-project.org/web/packages/scoringRules/index.html) served as a reference for this library. The authors did an outstanding work which greatly facilitated ours. The implementation of the ensemble-based metrics as jit-compiled numpy generalized `ufuncs` was first proposed in [properscoring](https://github.com/properscoring/properscoring), released under Apache License, Version 2.0.
+- The widely-used R package [`scoringRules`](https://cran.r-project.org/web/packages/scoringRules/index.html)
+served as a reference for this library, which greatly facilitated our work. We are additionally
+grateful for fruitful discussions with the authors.
+- The quality of this library has also benefited a lot from discussions with (and contributions from)
+Nick Loveday and Tennessee Leeuwenburg, whose python library [`scores`](https://github.com/nci/scores)
+similarly provides a comprehensive collection of forecast evaluation methods.

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/_templates/module.rst

@@ -0,0 +1,62 @@
+{{ objname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :members:
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+   {% for item in modules %}
+   {{ item }}
+   {%- endfor %}
+
+{% endif %}
+{% endblock %}