Merge pull request #3343 from agriyakhetarpal/pst-new-changes

Updates for PyData theme 0.14.0

.github/workflows/run_periodic_tests.yml

@@ -111,6 +111,10 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: nox -s doctests
 
+      - name: Check if the documentation can be built
+        if: matrix.os == 'ubuntu-latest'
+        run: nox -s docs
+
       - name: Install dev dependencies and run example tests
         if: matrix.os == 'ubuntu-latest'
         run: nox -s examples

.github/workflows/test_on_push.yml

@@ -4,6 +4,9 @@ on:
   workflow_dispatch:
   pull_request:
 
+env:
+  FORCE_COLOR: 3
+
 concurrency:
   # github.workflow: name of the workflow, so that we don't cancel other workflows
   # github.event.pull_request.number || github.ref: pull request number or branch name if not a pull request
@@ -256,13 +259,59 @@ jobs:
       - name: Run integration tests for ${{ matrix.os }} with Python ${{ matrix.python-version }}
         run: nox -s integration
 
+# Runs only on Ubuntu with Python 3.11. Skips IDAKLU module compilation
+# for speedups, which is already tested in other jobs.
+  run_doctests:
+    needs: style
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    name: Doctests (ubuntu-latest / Python 3.11)
+
+    steps:
+      - name: Check out PyBaMM repository
+        uses: actions/checkout@v4
+
+      # Install and cache apt packages
+      - name: Install Linux system dependencies
+        uses: awalsh128/[email protected]
+        with:
+          packages: gfortran gcc graphviz pandoc
+          execute_install_scripts: true
+
+      # dot -c is for registering graphviz fonts and plugins
+      - name: Install OpenBLAS and TeXLive for Linux
+        run: |
+          sudo apt-get update
+          sudo dot -c
+          sudo apt-get install libopenblas-dev texlive-latex-extra dvipng
+
+      - name: Set up Python 3.11
+        id: setup-python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+          cache: 'pip'
+          cache-dependency-path: setup.py
+
+      - name: Install PyBaMM dependencies
+        run: |
+          pip install --upgrade pip wheel setuptools nox
+          pip install -e .[all,docs]
+
+      - name: Install docs dependencies and run doctests for GNU/Linux with Python 3.11
+        run: nox -s doctests
+
+      - name: Check if the documentation can be built for GNU/Linux with Python 3.11
+        run: nox -s docs
+
   # Runs only on Ubuntu with Python 3.11
-  run_doctests_and_example_tests:
+  run_example_tests:
     needs: style
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
-    name: Doctests and notebooks (ubuntu-latest / Python 3.11)
+    name: Example notebooks (ubuntu-latest / Python 3.11)
 
     steps:
       - name: Check out PyBaMM repository
@@ -311,9 +360,6 @@ jobs:
       - name: Install SuiteSparse and SUNDIALS on GNU/Linux
         run: nox -s pybamm-requires
 
-      - name: Install docs dependencies and run doctests for GNU/Linux with Python 3.11
-        run: nox -s doctests
-
       - name: Install dev dependencies and run example tests for GNU/Linux with Python 3.11
         run: nox -s examples
 

CONTRIBUTING.md

@@ -72,7 +72,7 @@ python -m pip install pre-commit
 pre-commit run ruff
 ```
 
-ruff is configured inside the file `pre-commit-config.yaml`, allowing us to ignore some errors. If you think this should be added or removed, please submit an [issue](#issues)
+ruff is configured inside the file `pre-commit-config.yaml`, allowing us to ignore some errors. If you think this should be added or removed, please submit an [issue](https://github.com/pybamm-team/PyBaMM/issues)
 
 When you commit your changes they will be checked against ruff automatically (see [Pre-commit checks](#pre-commit-checks)).
 
@@ -347,17 +347,17 @@ Using [Sphinx](http://www.sphinx-doc.org/en/stable/) the documentation in `docs`
 
 ### Building the documentation
 
-To test and debug the documentation, it's best to build it locally. To do this, navigate to your PyBaMM directory in a console, and then type:
+To test and debug the documentation, it's best to build it locally. To do this, navigate to your PyBaMM directory in a console, and then type (on GNU/Linux, macOS, and Windows):
 
 ```
-nox -s docs (GNU/Linux, MacOS and Windows)
+nox -s docs
 ```
 
-And then visit the webpage served at http://127.0.0.1:8000. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded.
+And then visit the webpage served at `http://127.0.0.1:8000`. Each time a change to the documentation source is detected, the HTML is rebuilt and the browser automatically reloaded. In CI, the docs are built and tested using the `docs` session in the `noxfile.py` file with warnings turned into errors, to fail the build. The warnings can be removed or ignored by adding the appropriate warning identifier to the `suppress_warnings` list in `docs/conf.py`.
 
 ### Example notebooks
 
-Major PyBaMM features are showcased in [Jupyter notebooks](https://jupyter.org/) stored in the [docs/source/examples directory](docs/source/examples/notebooks). Which features are "major" is of course wholly subjective, so please discuss on GitHub first!
+Major PyBaMM features are showcased in [Jupyter notebooks](https://jupyter.org/) stored in the [docs/source/examples directory](https://github.com/pybamm-team/PyBaMM/tree/develop/docs/source/examples). Which features are "major" is of course wholly subjective, so please discuss on GitHub first!
 
 All example notebooks should be listed in [docs/source/examples/index.rst](https://github.com/pybamm-team/PyBaMM/blob/develop/docs/source/examples/index.rst). Please follow the (naming and writing) style of existing notebooks where possible.
 
@@ -375,7 +375,7 @@ pybamm.print_citations()
 
 to the end of a script will print all citations that were used by that script. This will print BibTeX information to the terminal; passing a filename to `print_citations` will print the BibTeX information to the specified file instead.
 
-When you contribute code to PyBaMM, you can add your own papers that you would like to be cited if that code is used. First, add the BibTeX for your paper to [CITATIONS.bib](pybamm/CITATIONS.bib). Then, add the line
+When you contribute code to PyBaMM, you can add your own papers that you would like to be cited if that code is used. First, add the BibTeX for your paper to [CITATIONS.bib](https://github.com/pybamm-team/PyBaMM/blob/develop/pybamm/CITATIONS.bib). Then, add the line
 
 ```python3
 pybamm.citations.register("your_paper_bibtex_identifier")
@@ -395,7 +395,7 @@ Configuration files:
 setup.py
 ```
 
-Note that this file must be kept in sync with the version number in [pybamm/**init**.py](pybamm/__init__.py).
+Note that this file must be kept in sync with the version number in [pybamm/**init**.py](https://github.com/pybamm-team/PyBaMM/blob/develop/pybamm/__init__.py).
 
 ### Continuous Integration using GitHub actions
 
@@ -431,9 +431,9 @@ Editable notebooks are made available using [Google Colab](https://colab.researc
 
 GitHub does some magic with particular filenames. In particular:
 
-- The first page people see when they go to [our GitHub page](https://github.com/pybamm-team/PyBaMM) displays the contents of [README.md](README.md), which is written in the [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Some guidelines can be found [here](https://help.github.com/articles/about-readmes/).
-- The license for using PyBaMM is stored in [LICENSE](LICENSE.txt), and [automatically](https://help.github.com/articles/adding-a-license-to-a-repository/) linked to by GitHub.
-- This file, [CONTRIBUTING.md](CONTRIBUTING.md) is recognised as the contribution guidelines and a link is [automatically](https://github.com/blog/1184-contributing-guidelines) displayed when new issues or pull requests are created.
+- The first page people see when they go to [our GitHub page](https://github.com/pybamm-team/PyBaMM) displays the contents of [README.md](https://github.com/pybamm-team/PyBaMM/blob/develop/README.md), which is written in the [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) format. Some guidelines can be found [here](https://help.github.com/articles/about-readmes/).
+- The license for using PyBaMM is stored in [LICENSE](https://github.com/pybamm-team/PyBaMM/blob/develop/LICENSE.txt), and [automatically](https://help.github.com/articles/adding-a-license-to-a-repository/) linked to by GitHub.
+- This file, [CONTRIBUTING.md](https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md) is recognised as the contribution guidelines and a link is [automatically](https://github.com/blog/1184-contributing-guidelines) displayed when new issues or pull requests are created.
 
 ## Acknowledgements
 

docs/_static/pybamm.css

@@ -152,6 +152,11 @@ html[data-theme="dark"] .DocSearch-Commands-Key {
 .DocSearch-Hit-source {
   background: var(--pst-color-background);
 }
+
+.DocSearch-Hit-icon {
+  height: 30px;
+}
+
 .DocSearch-Button {
   border-radius: 6px;
 }
@@ -187,5 +192,5 @@ html[data-theme="light"] .DocSearch-Logo svg rect.cls-1 {
 /* Search field dark theme corrections */
 
 html[data-theme="dark"] .DocSearch-Button {
-  background: var(--pst-color-on-surface);
+  background: var(--pst-color-background);
 }

docs/conf.py

@@ -142,12 +142,6 @@
         },
     ],
     "collapse_navigation": True,
-    "external_links": [
-        {
-            "name": "Contributing",
-            "url": "https://github.com/pybamm-team/PyBaMM/tree/develop/CONTRIBUTING.md",
-        },
-    ],
     # should be kept versioned to use for the version warning bar
     "switcher": {
         "version_match": version,

docs/index.rst

@@ -16,6 +16,7 @@ PyBaMM documentation
    User Guide <source/user_guide/index>
    source/api/index
    source/examples/index
+   Contributing <source/user_guide/contributing>
 
 **Version**: |version|
 
@@ -106,7 +107,7 @@ explore the effect of different battery designs and modeling assumptions under a
 
       +++
 
-      .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md
+      .. button-link:: source/user_guide/contributing.html
          :expand:
          :color: secondary
          :click-parent:

docs/source/user_guide/contributing.md

@@ -0,0 +1,5 @@
+<!-- a stub file to add CONTRIBUTING.md from the root directory
+to the hosted docs -->
+
+```{include} ../../../CONTRIBUTING.md
+```

docs/source/user_guide/index.md

@@ -24,6 +24,14 @@ fundamentals/index
 fundamentals/battery_models
 ```
 
+```{toctree}
+---
+caption: Contributing guide
+maxdepth: 1
+---
+contributing
+```
+
 # Example notebooks
 
 PyBaMM ships with example notebooks that demonstrate how to use it and reveal some of its

docs/source/user_guide/installation/index.rst

@@ -117,7 +117,7 @@ Installable with ``pip install "pybamm[docs]"``
 ================================================================================================= ================== ================== =======================================================================
 Dependency                                                                                        Minimum Version    pip extra          Notes
 ================================================================================================= ================== ================== =======================================================================
-`sphinx <https://www.sphinx-doc.org/en/master/>`__                                                1.5.0              docs               Sphinx makes it easy to create intelligent and beautiful documentation.
+`sphinx <https://www.sphinx-doc.org/en/master/>`__                                                \-                 docs               Sphinx makes it easy to create intelligent and beautiful documentation.
 `pydata-sphinx-theme <https://pydata-sphinx-theme.readthedocs.io/en/stable/>`__                   \-                 docs               A clean, Bootstrap-based Sphinx theme.
 `sphinx_design <https://sphinx-design.readthedocs.io/en/latest/>`__                               \-                 docs               A sphinx extension for designing.
 `sphinx-copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`__                       \-                 docs               To copy codeblocks.

docs/source/user_guide/installation/install-from-source.rst

@@ -246,8 +246,9 @@ Doctests, examples, and coverage
 - ``nox -s coverage``: Measure current test coverage and generate a coverage report.
 - ``nox -s quick``: Run integration tests, unit tests, and doctests sequentially.
 
-Extra tips while using Nox
---------------------------
+Extra tips while using ``Nox``
+------------------------------
+
 Here are some additional useful commands you can run with ``Nox``:
 
 - ``--verbose or -v``: Enables verbose mode, providing more detailed output during the execution of Nox sessions.
@@ -257,6 +258,7 @@ Here are some additional useful commands you can run with ``Nox``:
 - ``--install-only``: Skips the test execution and only performs the installation step defined in the Nox sessions.
 - ``--nocolor``: Disables the color output in the console during the execution of Nox sessions.
 - ``--report output.json``: Generates a JSON report of the Nox session execution and saves it to the specified file, in this case, "output.json".
+- ``nox -s docs --non-interactive``: Builds the documentation without serving it locally (using ``sphinx-build`` instead of ``sphinx-autobuild``).
 
 Troubleshooting
 ===============