diff --git a/.github/workflows/run_periodic_tests.yml b/.github/workflows/run_periodic_tests.yml index b403630db5..2f9b5d89a8 100644 --- a/.github/workflows/run_periodic_tests.yml +++ b/.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 diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml index 839d53306f..b740da2e1b 100644 --- a/.github/workflows/test_on_push.yml +++ b/.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/cache-apt-pkgs-action@v1.3.0 + 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 577dbd67c6..a6aa6987c2 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/docs/_static/pybamm.css b/docs/_static/pybamm.css index a795e50f23..614716d24a 100644 --- a/docs/_static/pybamm.css +++ b/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); } diff --git a/docs/conf.py b/docs/conf.py index 1cb1a521ae..a96d139b12 100644 --- a/docs/conf.py +++ b/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, diff --git a/docs/index.rst b/docs/index.rst index 3e5d54ecb5..bf0d34e1a0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ PyBaMM documentation User Guide source/api/index source/examples/index + 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: diff --git a/docs/source/user_guide/contributing.md b/docs/source/user_guide/contributing.md new file mode 100644 index 0000000000..3f967fa93f --- /dev/null +++ b/docs/source/user_guide/contributing.md @@ -0,0 +1,5 @@ + + +```{include} ../../../CONTRIBUTING.md +``` diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md index e288a67e28..8b28fc6636 100644 --- a/docs/source/user_guide/index.md +++ b/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 diff --git a/docs/source/user_guide/installation/index.rst b/docs/source/user_guide/installation/index.rst index 9710a3593a..6338323e79 100644 --- a/docs/source/user_guide/installation/index.rst +++ b/docs/source/user_guide/installation/index.rst @@ -117,7 +117,7 @@ Installable with ``pip install "pybamm[docs]"`` ================================================================================================= ================== ================== ======================================================================= Dependency Minimum Version pip extra Notes ================================================================================================= ================== ================== ======================================================================= -`sphinx `__ 1.5.0 docs Sphinx makes it easy to create intelligent and beautiful documentation. +`sphinx `__ \- docs Sphinx makes it easy to create intelligent and beautiful documentation. `pydata-sphinx-theme `__ \- docs A clean, Bootstrap-based Sphinx theme. `sphinx_design `__ \- docs A sphinx extension for designing. `sphinx-copybutton `__ \- docs To copy codeblocks. diff --git a/docs/source/user_guide/installation/install-from-source.rst b/docs/source/user_guide/installation/install-from-source.rst index f8aa4968d9..0aa50cf8a8 100644 --- a/docs/source/user_guide/installation/install-from-source.rst +++ b/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 =============== diff --git a/noxfile.py b/noxfile.py index 96a0e82809..c215c73ca5 100644 --- a/noxfile.py +++ b/noxfile.py @@ -16,13 +16,6 @@ "SUNDIALS_INST": f"{homedir}/.local", "LD_LIBRARY_PATH": f"{homedir}/.local/lib:", } -# Do not stdout ANSI colours on GitHub Actions -if os.getenv("CI") == "true": - os.environ["NO_COLOR"] = "1" - # The setup-python action installs and caches dependencies by default, so we skip - # installing them again in nox environments. The dev and docs sessions will still - # require a virtual environment, but we don't run them in the CI - nox.options.default_venv_backend = "none" def set_environment_variables(env_dict, session): @@ -46,7 +39,7 @@ def run_pybamm_requires(session): """Download, compile, and install the build-time requirements for Linux and macOS: the SuiteSparse and SUNDIALS libraries.""" # noqa: E501 set_environment_variables(PYBAMM_ENV, session=session) if sys.platform != "win32": - session.run_always("pip", "install", "wget", "cmake") + session.install("wget", "cmake", silent=False) session.run("python", "scripts/install_KLU_Sundials.py") if not os.path.exists("./pybind11"): session.run( @@ -57,18 +50,18 @@ def run_pybamm_requires(session): external=True, ) else: - session.error("nox -s pybamm-requires is only available on Linux & MacOS.") + session.error("nox -s pybamm-requires is only available on Linux & macOS.") @nox.session(name="coverage") def run_coverage(session): """Run the coverage tests and generate an XML report.""" set_environment_variables(PYBAMM_ENV, session=session) - session.run_always("pip", "install", "coverage") - session.run_always("pip", "install", "-e", ".[all]") + session.install("coverage", silent=False) + session.install("-e", ".[all]", silent=False) if sys.platform != "win32": - session.run_always("pip", "install", "-e", ".[odes]") - session.run_always("pip", "install", "-e", ".[jax]") + session.install("-e", ".[odes]", silent=False) + session.install("-e", ".[jax]", silent=False) session.run("coverage", "run", "--rcfile=.coveragerc", "run-tests.py", "--nosub") session.run("coverage", "combine") session.run("coverage", "xml") @@ -78,16 +71,16 @@ def run_coverage(session): def run_integration(session): """Run the integration tests.""" set_environment_variables(PYBAMM_ENV, session=session) - session.run_always("pip", "install", "-e", ".[all]") + session.install("-e", ".[all]", silent=False) if sys.platform == "linux": - session.run_always("pip", "install", "-e", ".[odes]") + session.install("-e", ".[odes]", silent=False) session.run("python", "run-tests.py", "--integration") @nox.session(name="doctests") def run_doctests(session): """Run the doctests and generate the output(s) in the docs/build/ directory.""" - session.run_always("pip", "install", "-e", ".[all,docs]") + session.install("-e", ".[all,docs]", silent=False) session.run("python", "run-tests.py", "--doctest") @@ -95,10 +88,10 @@ def run_doctests(session): def run_unit(session): """Run the unit tests.""" set_environment_variables(PYBAMM_ENV, session=session) - session.run_always("pip", "install", "-e", ".[all]") + session.install("-e", ".[all]", silent=False) if sys.platform == "linux": - session.run_always("pip", "install", "-e", ".[odes]") - session.run_always("pip", "install", "-e", ".[jax]") + session.install("-e", ".[odes]", silent=False) + session.install("-e", ".[jax]", silent=False) session.run("python", "run-tests.py", "--unit") @@ -106,8 +99,8 @@ def run_unit(session): def run_examples(session): """Run the examples tests for Jupyter notebooks.""" set_environment_variables(PYBAMM_ENV, session=session) + session.install("-e", ".[all,dev]", silent=False) notebooks_to_test = session.posargs if session.posargs else [] - session.run_always("pip", "install", "-e", ".[all,dev]") session.run("pytest", "--nbmake", *notebooks_to_test, external=True) @@ -115,7 +108,7 @@ def run_examples(session): def run_scripts(session): """Run the scripts tests for Python scripts.""" set_environment_variables(PYBAMM_ENV, session=session) - session.run_always("pip", "install", "-e", ".[all]") + session.install("-e", ".[all]", silent=False) session.run("python", "run-tests.py", "--scripts") @@ -124,8 +117,8 @@ def set_dev(session): """Install PyBaMM in editable mode.""" set_environment_variables(PYBAMM_ENV, session=session) envbindir = session.bin - session.install("-e", ".[all]") - session.install("cmake") + session.install("-e", ".[all]", silent=False) + session.install("cmake", silent=False) if sys.platform == "linux" or sys.platform == "darwin": session.run( "echo", @@ -141,10 +134,10 @@ def set_dev(session): def run_tests(session): """Run the unit tests and integration tests sequentially.""" set_environment_variables(PYBAMM_ENV, session=session) - session.run_always("pip", "install", "-e", ".[all]") + session.install("-e", ".[all]", silent=False) if sys.platform == "linux" or sys.platform == "darwin": - session.run_always("pip", "install", "-e", ".[odes]") - session.run_always("pip", "install", "-e", ".[jax]") + session.install("-e", ".[odes]", silent=False) + session.install("-e", ".[jax]", silent=False) session.run("python", "run-tests.py", "--all") @@ -152,9 +145,11 @@ def run_tests(session): def build_docs(session): """Build the documentation and load it in a browser tab, rebuilding on changes.""" envbindir = session.bin - session.install("-e", ".[all,docs]") + session.install("-e", ".[all,docs]", silent=False) session.chdir("docs") - session.run( + # Local development + if session.interactive: + session.run( "sphinx-autobuild", "-j", "auto", @@ -162,13 +157,26 @@ def build_docs(session): "-qT", ".", f"{envbindir}/../tmp/html", - ) + ) + # Runs in CI only, treating warnings as errors + else: + session.run( + "sphinx-build", + "-j", + "auto", + "-b", + "html", + "-W", + "--keep-going", + ".", + f"{envbindir}/../tmp/html", + ) @nox.session(name="pre-commit") def lint(session): """Check all files against the defined pre-commit hooks.""" - session.install("pre-commit") + session.install("pre-commit", silent=False) session.run("pre-commit", "run", "--all-files") diff --git a/setup.py b/setup.py index 9dd4d41cd3..11ac2e7563 100644 --- a/setup.py +++ b/setup.py @@ -210,8 +210,7 @@ def compile_KLU(): ], extras_require={ "docs": [ - "sphinx>=6", - "sphinx_rtd_theme>=0.5", + "sphinx", "pydata-sphinx-theme", "sphinx_design", "sphinx-copybutton",