Migrate to the PyData Sphinx theme

This theme displays the top-level TOC elements in the page header,
individual pages in the active section in the left sidebar, and
within-page headers in the right sidebar.

This distinction between top-level elements (e.g., the Getting Started
tutorial, the How-to guides, the API documentation), the section pages
(e.g., each page of the Getting Started tutorial), and page headings
makes the documentation easier to navigate.

As a bonus, the theme supports light and dark versions, and is used by
many popular Python packages (e.g., NumPy, SciPy, Pandas, Matplotlib).

doc/api/index.rst

-API documentation
-=================
+API
+===
 
 The :mod:`pypfilt` module provides top-level functions for running forecasts
 and simulating observations from simulation models:
@@ -73,6 +73,7 @@ table), while others are likely of no use outside of pypfilt_ (see the
 .. toctree::
    :maxdepth: 2
    :caption: Key modules
+   :hidden:
 
    pypfilt
    scenario
@@ -89,6 +90,7 @@ table), while others are likely of no use outside of pypfilt_ (see the
 .. toctree::
    :maxdepth: 2
    :caption: Secondary modules
+   :hidden:
 
    adaptive
    build

doc/conf.py

@@ -19,13 +19,8 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
     'sphinx.ext.mathjax',
-    'sphinx_rtd_theme',
 ]
 
-# The MathJax CDN will not be available after 30 April 2017, and this will be
-# fixed in Sphinx 1.5.5 (https://github.com/sphinx-doc/sphinx/issues/3599).
-mathjax_path = 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
-
 # Ignore missing dependencies when building the documentation.
 autodoc_mock_imports = ['h5py', 'lhs', 'numpy', 'scipy', 'tomli', 'tomli_w']
 
@@ -116,12 +111,50 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 # html_theme_options = {}
+html_theme_options = {
+    'logo': {
+        'text': 'pypfilt',
+    },
+    'show_toc_level': 4,
+    'show_nav_level': 4,
+    'navigation_depth': 2,
+    'navigation_with_keys': False,
+    'use_edit_page_button': True,
+    'header_links_before_dropdown': 6,
+    'icon_links_label': 'Quick Links',
+    'icon_links': [
+        {
+            'name': 'Bitbucket',
+            'url': 'https://bitbucket.org/robmoss/particle-filter-for-python/',
+            'icon': 'fa-brands fa-bitbucket',
+            'type': 'fontawesome',
+        },
+        {
+            'name': 'GitLab',
+            'url': 'https://gitlab.unimelb.edu.au/rgmoss/particle-filter-for-python',
+            'icon': 'fa-brands fa-square-gitlab',
+            'type': 'fontawesome',
+        },
+        {
+            'name': 'PyPI',
+            'url': 'https://pypi.org/project/pypfilt',
+            'icon': 'fa-brands fa-python',
+        },
+    ],
+}
+
+html_context = {
+    'bitbucket_user': 'robmoss',
+    'bitbucket_repo': 'particle-filter-for-python',
+    'bitbucket_version': 'master',
+    'doc_path': 'doc',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

doc/changelog.rst → doc/development/changelog.rst

 Change Log
 ==========
 
-.. include:: ../NEWS.rst
+.. include:: ../../NEWS.rst

doc/development/index.rst

+.. _development:
+
+Development
+===========
+
+These page contain information about how pypfilt_ is developed, and how you can contribute to this project.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   contributing
+   testing
+   release-process
+   unicode
+   editable-installs
+   changelog

doc/release-process.rst → doc/development/release-process.rst

@@ -14,18 +14,16 @@ tagging the relevant commit with the new version number.
 * Update the version number according to the
   `versioning scheme <https://www.python.org/dev/peps/pep-0440/>`__.
 
-   * Update the version number in ``doc/conf.py``.
-     The full version must **always** be updated, the short (X.Y) version
-     **does not** need to be updated if the version number is being increased
-     from X.Y.Z to X.Y.Z+1.
+  * Update the version number in ``doc/conf.py``.
+    The full version must **always** be updated, the short (X.Y) version **does not** need to be updated if the version number is being increased from X.Y.Z to X.Y.Z+1.
 
-   * Update the version number in ``pyproject.toml``.
+  * Update the version number in ``pyproject.toml``.
 
 * Check whether the copyright year(s) need to be updated in:
 
-   * ``LICENSE``
+  * ``LICENSE``
 
-   * ``doc/conf.py``
+  * ``doc/conf.py``
 
 * Describe the changes at the top of ``NEWS.rst`` under a heading of the form
   ``X.Y.Z (YYYY-MM-DD)``, which identifies the new version number and the

doc/testing.rst → doc/development/testing.rst

@@ -39,7 +39,7 @@ The nox configuration
 
 The ``noxfile.py`` contents are shown below, and include targets that check whether the documentation in ``./doc`` builds correctly.
 
-.. literalinclude:: ../noxfile.py
+.. literalinclude:: ../../noxfile.py
    :language: python
 
 .. _nox: https://nox.thea.codes/

doc/getting-started/index.rst

@@ -5,10 +5,10 @@ Getting Started
 
 This guide assumes that you have already installed pypfilt_:
 
-   .. code-block:: shell
+.. code-block:: shell
 
-      # Install pypfilt with plotting support.
-      pip install pypfilt[plot]
+   # Install pypfilt with plotting support.
+   pip install pypfilt[plot]
 
 See the :ref:`installation instructions <install>` for further details.
 
@@ -20,7 +20,9 @@ This guide shows how to build a simulation model, generate simulated observation
    Forecasts for :math:`x(t)`, :math:`y(t)`, and :math:`z(t)` of the :class:`~pypfilt.examples.lorenz.Lorenz63` system at time :math:`t=20`.
 
 .. toctree::
+   :hidden:
 
+   install
    overview
    system
    model

doc/index.rst

@@ -17,6 +17,9 @@ Then you can use pypfilt_ to estimate the state and/or parameters of this system
 
    Forecasts for :math:`x(t)`, :math:`y(t)`, and :math:`z(t)` of the :class:`~pypfilt.examples.lorenz.Lorenz63` system at time :math:`t=20`.
 
+Contents
+--------
+
 Depending on your preferred learning style, start with any of the following:
 
 The :doc:`getting-started/index` tutorial
@@ -38,6 +41,9 @@ The :doc:`settings/index` guide
 The :doc:`api/index`
    Presents the details of each pypfilt_ component and is likely only of interest if you need to develop your own components.
 
+The :doc:`development/index` guide
+   Explains how pypfilt_ is developed and how to contribute to this project.
+
 License
 -------
 
@@ -62,29 +68,38 @@ If you use ``pypfilt``, please cite our `JOSS article <https://doi.org/10.21105/
      note = {Please cite this article and an archived release (see CITATION.cff)},
    }
 
-.. _user-docs:
-
 .. toctree::
    :maxdepth: 2
-   :caption: User Documentation
+   :hidden:
 
-   Home <self>
-   install
    getting-started/index
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
    concepts/index
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
    how-to/index
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
    settings/index
-   api/index
 
-.. _dev-docs:
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   api/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: Development
-
-   contributing
-   testing
-   release-process
-   unicode
-   editable-installs
-   changelog
+   :hidden:
+
+   development/index

requirements-rtd.txt

 sphinx~=7.0
-sphinx-rtd-theme~=1.3
+pydata-sphinx-theme~=0.15