From ded7b28615dc3ed6e22f0f6517852007825ec1b0 Mon Sep 17 00:00:00 2001 From: Andrew Davison Date: Thu, 10 Sep 2026 10:59:03 +0200 Subject: [PATCH] Build the documentation on Read the Docs --- .readthedocs.yaml | 20 ++++++++++++++ doc/README | 9 ++++--- doc/conf.py | 47 +++++++++++++++------------------ doc/developers/contributing.txt | 16 +++++------ pyproject.toml | 2 +- 5 files changed, 55 insertions(+), 39 deletions(-) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..14f30713 --- /dev/null +++ b/.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 diff --git a/doc/README b/doc/README index d2bc274c..1991815b 100644 --- a/doc/README +++ b/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/ diff --git a/doc/conf.py b/doc/conf.py index 2f3ed2eb..e3d923ed 100644 --- a/doc/conf.py +++ b/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), +} diff --git a/doc/developers/contributing.txt b/doc/developers/contributing.txt index 6b99d729..e405f689 100644 --- a/doc/developers/contributing.txt +++ b/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 \ No newline at end of file +.. _contents: http://software.incf.org/software/pynn/pynn/folder_contents \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index bd0a8ab9..7e650904 100644 --- a/pyproject.toml +++ b/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"]