Build the documentation on Read the Docs

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs build configuration
+# https://docs.readthedocs.com/platform/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: doc/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
+        - plotting

doc/README

@@ -12,8 +12,9 @@ Many of the files contain examples of interactive Python sessions. The validity
 
     $ make doctest
 
-To copy the built docs to a checkout of the NeuralEnsemble server sources:
+The published documentation is built automatically by `Read the Docs`_ on every push
+to ``master``, and is served at http://neuralensemble.org/docs/PyNN/. Building locally
+with ``make html`` is only needed to preview changes.
 
-    $ rsync -avz doc/_build/html/ ~/dev/web/neuralensemble.github.io/docs/PyNN/
-
-.. _Sphinx: http://sphinx.pocoo.org/
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _`Read the Docs`: https://pynn.readthedocs.io/

doc/conf.py

@@ -13,28 +13,24 @@
 
 import sys
 import os
+import unittest.mock as mock
 
 
-if True:  # mock NEURON
-    import unittest.mock as mock
-    # mocks are only wanted when building docs, not when running doctests
-    # is there any way to use them selectively, like this?
-    # also, the matplotlib figures need the real modules.
+# The API reference is generated from `pyNN.neuron`, so `pyNN.neuron` must import
+# successfully. Mocking the `neuron` module means NEURON does not have to be installed
+# to build the documentation; none of the other backends are used by autodoc.
+# Note that the mock is not wanted when running doctests (`make doctest`), which use
+# either `pyNN.mock` or a real simulator.
 
-    class MockNeuronModule(mock.Mock):
-        nrn_dll_loaded = []
-        nhost = lambda self: 1
-        id = lambda self: 1
-        Section = object
-        set_maxstep = lambda self, x: 10.0
-    sys.modules["neuron"] = MockNeuronModule()
+class MockNeuronModule(mock.Mock):
+    nrn_dll_loaded = []
+    nhost = lambda self: 1
+    id = lambda self: 1
+    Section = object
+    set_maxstep = lambda self, x: 10.0
 
-if False:  # mock NEST
-    import unittest.mock as mock
 
-    class MockNESTModule(mock.Mock):
-        GetKernelStatus = lambda self: {'num_processes': 1}
-    sys.modules["nest"] = MockNESTModule()
+sys.modules["neuron"] = MockNeuronModule()
 
 # 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
@@ -50,13 +46,11 @@ class MockNESTModule(mock.Mock):
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
+              'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.viewcode'
               ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
 # The suffix of source filenames.
 source_suffix = '.txt'
 
@@ -74,11 +68,11 @@ class MockNESTModule(mock.Mock):
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
-# The short X.Y version.
-version = '0.13'
+
 # The full version, including alpha/beta/rc tags.
-release = '0.13.0'
+from pyNN import __version__ as release  # noqa: E402
+# The short X.Y version.
+version = '.'.join(release.split('.')[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -296,4 +290,7 @@ class MockNESTModule(mock.Mock):
 
 # -- inter-Sphinx mapping options ----------------------------------------------
 
-intersphinx_mapping = {'python': ('http://docs.python.org/3.9', None)}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+}

doc/developers/contributing.txt

@@ -162,8 +162,7 @@ Making a release
 ================
 
 To make a release of PyNN requires you to have permissions to upload PyNN
-packages to the `Python Package Index`_, and to
-upload documentation to the neuralensemble.org server. If you are interested
+packages to the `Python Package Index`_. If you are interested
 in becoming release manager for PyNN, please contact us via the `mailing list`_.
 
 When you think a release is ready, run through the following checklist one
@@ -180,8 +179,8 @@ last time:
       you should do this on at least two Linux systems and one Mac OS X system.
 * does the documentation build without errors? You should then at least skim
       the generated HTML pages to check for obvious problems.
-* have you updated the version numbers in :file:`pyproject.toml`, :file:`pyNN/__init__.py`,
-      :file:`doc/conf.py` and :file:`doc/installation.txt`?
+* have you updated the version numbers in :file:`pyproject.toml`,
+      :file:`pyNN/__init__.py` and :file:`doc/installation.txt`?
 * have you updated the changelog?
 
 Once you've confirmed all the above, create source and wheel packages using::
@@ -195,9 +194,9 @@ Now you should commit any changes, then tag with the release number as follows::
 
     $ git tag x.y.z
 
-where ``x.y.z`` is the release number. You should now upload the documentation
-to http://neuralensemble.org/docs/PyNN/ by updating the `neuralensemble.github.io`
-repository (in the :file:`docs/PyNN` directory).
+where ``x.y.z`` is the release number. The documentation at
+http://neuralensemble.org/docs/PyNN/ is rebuilt automatically by Read the Docs, so
+there is nothing to upload.
 
 If this is a final release, there are a few more steps:
 
@@ -234,5 +233,4 @@ If this is a final release, there are a few more steps:
 .. _`issue tracker`: https://github.com/NeuralEnsemble/PyNN/issues/
 .. _fork: https://github.com/NeuralEnsemble/PyNN/fork
 .. _`PyNN repository`: https://github.com/NeuralEnsemble/PyNN/
-.. _contents: http://software.incf.org/software/pynn/pynn/folder_contents
-.. _`neuralensemble.github.io`: https://github.com/NeuralEnsemble/neuralensemble.github.io
+.. _contents: http://software.incf.org/software/pynn/pynn/folder_contents

pyproject.toml

@@ -34,7 +34,7 @@ dependencies = [
 
 [project.optional-dependencies]
 test = ["pytest", "pytest-xdist", "pytest-cov", "flake8", "wheel", "mpi4py", "scipy", "matplotlib", "Cheetah3", "h5py", "Jinja2"]
-doc = ["sphinx", "sphinxawesome_theme"]
+doc = ["sphinx>=7,<10", "sphinxawesome-theme>=6,<7"]
 examples = ["matplotlib", "scipy"]
 plotting = ["matplotlib", "scipy"]
 MPI = ["mpi4py"]