Add documentation build steps, move doc dependencies into pyproject.toml

.github/workflows/alns.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.7', '3.8', '3.9', '3.10' ]
+        python-version: [ '3.8', '3.9', '3.10', '3.11' ]
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
     -   id: flake8
 
 -   repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
     -   id: isort
 

.readthedocs.yaml

@@ -4,7 +4,9 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.9"
-
-python:
-  install:
-    - requirements: docs/requirements.txt
+  commands:
+    - pip install poetry
+    - poetry install --with docs
+    - poetry run make html --directory=docs
+    - mkdir _readthedocs/
+    - mv docs/build/html _readthedocs/ 

docs/README.md

@@ -0,0 +1,14 @@
+# Documentation
+
+This directory hosts the documentation. 
+We use Sphinx for this.
+The documentation has a few unique dependencies that are listed in the optional `docs` group in the top-level `pyproject.toml`.
+If you want to build the documentation, make sure to install that group (using `poetry install --with docs` or `--only docs`).
+
+The Makefile in this directory can be used to build the documentation.
+Running the command `poetry run make help` from this directory provides an overview of the available options.
+In particular `poetry run make html` is useful, as that will build the documentation in the exact same way as it will be displayed on readthedocs later.
+
+> Alternatively, one can run `poetry run make html --directory=docs` from the project root as well.
+
+Finally, all Sphinx-related settings are configured in `docs/source/conf.py`.

docs/source/setup/contributing.rst

@@ -60,11 +60,5 @@ This greatly reduces the job of maintaining and releasing the software.
 - Each function, class, method, and attribute needs to be documented using docstrings.
   We conform to the `NumPy docstring standard <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_.
 - If you are adding new functionality, you need to add it to the documentation by editing (or creating) the appropriate file in ``docs/source/``.
-- Make sure your documentation changes parse correctly. Change into the top-level ``docs/`` directory and type:
-
-  .. code-block:: shell
-
-     make clean
-     make html
-
-  Check that the build output does not have *any* warnings due to your changes.
+- Make sure your documentation changes parse correctly.
+  See the documentation in the ``docs/`` directory for details on how to build the documentation locally.

pyproject.toml

@@ -30,7 +30,7 @@ classifiers = [
 "Tracker" = "https://github.com/N-Wouda/ALNS/issues"
 
 [tool.poetry.dependencies]
-python = "^3.7"
+python = "^3.8, <4.0"
 numpy = ">=1.15.2"
 matplotlib = ">=2.2.0"
 
@@ -40,6 +40,20 @@ pytest = ">=6.0.0"
 pytest-cov = ">=2.6.1"
 codecov = "*"
 
+# This optional docs group is needed to build the documentation. It is not 
+# required by the package itself.
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+tomli = ">=2.0.1"
+nbsphinx = ">=0.8.9"
+ipython = ">=8.6.0"
+numpydoc = ">=1.5.0"
+sphinx_rtd_theme = ">=0.5.1"
+sphinx-autoapi = ">=2.0.1"
+docutils = "==0.16"
+
 # This optional examples group is needed to run the example notebooks, but not
 # required for the package itself.
 [tool.poetry.group.examples]