Squash Previous 6 commits

.github/workflows/test_on_push.yml

@@ -56,7 +56,7 @@ jobs:
         uses: awalsh128/cache-apt-pkgs-action@v1.3.0
         if: matrix.os == 'ubuntu-latest'
         with:
-          packages: gfortran gcc graphviz
+          packages: gfortran gcc graphviz pandoc
           execute_install_scripts: true
 
       # dot -c is for registering graphviz fonts and plugins

.gitignore

@@ -41,7 +41,7 @@ input/*
 !input/drive_cycles
 
 # keep images required by notebooks
-!examples/notebooks/Creating%20Models/SEI.png
+!docs/examples/notebooks/creating_models/SEI.png
 
 # simulation outputs
 out/
@@ -121,4 +121,15 @@ vcpkg_installed/
 
 # benchmarks
 html/
-results/
+results/
+
+# expression tree images for notebooks in docs
+!docs/source/examples/notebooks/expression_tree/expression_tree1.png
+!docs/source/examples/notebooks/expression_tree/expression_tree2.png
+!docs/source/examples/notebooks/expression_tree/expression_tree3.png
+!docs/source/examples/notebooks/expression_tree/expression_tree4.png
+!docs/source/examples/notebooks/expression_tree/expression_tree5.png
+
+# do not ignore SPM images for notebooks in docs
+!docs/source/examples/notebooks/models/spm1.png
+!docs/source/examples/notebooks/models/spm2.png

.lycheeignore

@@ -12,6 +12,3 @@ file:///home/runner/work/PyBaMM/PyBaMM/docs/source/user_guide/fundamentals/plot_
 # Errors in docs/source/user_guide/index.md
 file:///home/runner/work/PyBaMM/PyBaMM/docs/source/user_guide/api_docs
 
-# Errors in examples/notebooks/README.md
-file:///home/runner/work/PyBaMM/PyBaMM/examples/notebooks/using-submodels.ipynb
-file:///home/runner/work/PyBaMM/PyBaMM/examples/notebooks/create-model.ipynb

.pre-commit-config.yaml

@@ -8,8 +8,8 @@ repos:
     hooks:
       - id: black
 
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.0.275"
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.0.276"
     hooks:
       - id: ruff
         args: [--ignore=E741, --exclude=__init__.py]

CHANGELOG.md

@@ -1,10 +1,21 @@
 # [Unreleased](https://github.com/pybamm-team/PyBaMM/)
 
+## Bug fixes
+
+## Features
+
+## Optimizations
+
+## Breaking changes
+
+- PyBaMM now has optional dependencies that can be installed with `pip install pybamm[option]` e.g. `pybamm[dev]` ([#3044](https://github.com/pybamm-team/PyBaMM/pull/3044))
+
 # [v23.5](https://github.com/pybamm-team/PyBaMM/tree/v23.5) - 2023-05-31
 
 ## Bug fixes
 
 - Realign 'count' increment in CasadiSolver._integrate() ([#2986](https://github.com/pybamm-team/PyBaMM/pull/2986))
+# [v23.5](https://github.com/pybamm-team/PyBaMM/tree/v23.5) - 2023-06-18
 
 ## Features
 
@@ -21,6 +32,7 @@
 
 ## Bug fixes
 
+- Realign 'count' increment in CasadiSolver._integrate() ([#2986](https://github.com/pybamm-team/PyBaMM/pull/2986))
 - Fix `pybamm_install_odes` and update the required SUNDIALS version ([#2958](https://github.com/pybamm-team/PyBaMM/pull/2958))
 - Fixed a bug where all data included in a BPX was incorrectly assumed to be given as a function of time.([#2957](https://github.com/pybamm-team/PyBaMM/pull/2957))
 - Remove brew install for Mac from the recommended developer installation options for SUNDIALS ([#2925](https://github.com/pybamm-team/PyBaMM/pull/2925))
@@ -29,7 +41,6 @@
 ## Breaking changes
 
 - Deprecate functionality to load parameter set from a csv file. Parameter sets must now be provided as python dictionaries ([#2959](https://github.com/pybamm-team/PyBaMM/pull/2959))
-- PyBaMM now has optional dependencies that can be installed with `pip install pybamm[option]` e.g. `pybamm[dev]` ([#3044](https://github.com/pybamm-team/PyBaMM/pull/3044))
 - Tox support for Installation & testing has now been replaced by Nox ([#3005](https://github.com/pybamm-team/PyBaMM/pull/3005))
 
 # [v23.4.1](https://github.com/pybamm-team/PyBaMM/tree/v23.4) - 2023-05-01
@@ -921,7 +932,7 @@ This release introduces many new features and optimizations. All models can now
 - Removed `Outer` and `Kron` nodes as no longer used ([#777](https://github.com/pybamm-team/PyBaMM/pull/777))
 - Moved `results` to separate repositories ([#761](https://github.com/pybamm-team/PyBaMM/pull/761))
 - The parameters "Bruggeman coefficient" must now be specified separately as "Bruggeman coefficient (electrolyte)" and "Bruggeman coefficient (electrode)"
-- The current classes (`GetConstantCurrent`, `GetUserCurrent` and `GetUserData`) have now been removed. Please refer to the [`change-input-current` notebook](https://github.com/pybamm-team/PyBaMM/blob/main/examples/notebooks/change-input-current.ipynb) for information on how to specify an input current
+- The current classes (`GetConstantCurrent`, `GetUserCurrent` and `GetUserData`) have now been removed. Please refer to the [`change-input-current` notebook](https://github.com/pybamm-team/PyBaMM/blob/develop/docs/source/examples/notebooks/change-input-current.ipynb) for information on how to specify an input current
 - Parameter functions must now use pybamm functions instead of numpy functions (e.g. `pybamm.exp` instead of `numpy.exp`), as these are then used to construct the expression tree directly. Generally, pybamm syntax follows numpy syntax; please get in touch if a function you need is missing.
 - The current must now be updated by changing "Current function [A]" or "C-rate" instead of "Typical current [A]"
 

CONTRIBUTING.md

@@ -173,7 +173,15 @@ To test all example scripts and notebooks, type
 nox -s examples
 ```
 
-If notebooks fail because of changes to pybamm, it can be a bit of a hassle to debug. In these cases, you can create a temporary export of a notebook's Python content using
+To edit the structure and how the Jupyter notebooks get rendered in the Sphinx documentation (using `nbsphinx`), install [Pandoc](https://pandoc.org/installing.html) on your system, either using `conda` (through the `conda-forge` channel)
+
+```bash
+conda install -c conda-forge pandoc
+```
+
+or refer to the [Pandoc installation instructions](https://pandoc.org/installing.html) specific to your platform.
+
+If notebooks fail because of changes to PyBaMM, it can be a bit of a hassle to debug. In these cases, you can create a temporary export of a notebook's Python content using
 
 ```bash
 python run-tests.py --debook examples/notebooks/notebook-name.ipynb script.py
@@ -394,4 +402,4 @@ GitHub does some magic with particular filenames. In particular:
 ## Acknowledgements
 
 This CONTRIBUTING.md file, along with large sections of the code infrastructure,
-was copied from the excellent [Pints GitHub repo](https://github.com/pints-team/pints)
+was copied from the excellent [Pints GitHub repo](https://github.com/pints-team/pints)

README.md

@@ -80,12 +80,12 @@ sim.solve()
 sim.plot()
 ```
 
-However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type, number of submesh points, methods for spatial discretisation and solver for integration (see DFN [script](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/scripts/DFN.py) or [notebook](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/models/DFN.ipynb)).
+However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type, number of submesh points, methods for spatial discretisation and solver for integration (see DFN [script](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/scripts/DFN.py) or [notebook](https://github.com/pybamm-team/PyBaMM/blob/develop/docs/source/examples/notebooks/models/DFN.ipynb)).
 
-For new users we recommend the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/Getting%20Started) guides. These are intended to be very simple step-by-step guides to show the basic functionality of PyBaMM, and can either be downloaded and used locally, or used online through [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop).
+For new users we recommend the [Getting Started](https://github.com/pybamm-team/PyBaMM/tree/develop/docs/source/examples/notebooks/getting_started/) guides. These are intended to be very simple step-by-step guides to show the basic functionality of PyBaMM, and can either be downloaded and used locally, or used online through [Google Colab](https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop).
 
-Further details can be found in a number of [detailed examples](https://github.com/pybamm-team/PyBaMM/blob/develop/examples/notebooks/README.md), hosted here on
-github. In addition, there is a [full API documentation](https://pybamm.readthedocs.io/en/latest/source/api/index.html),
+Further details can be found in a number of [detailed examples](https://github.com/pybamm-team/PyBaMM/blob/develop/docs/source/examples/notebooks/README.md), hosted here on
+github. In addition, there is a [full API documentation](https://docs.pybamm.org/en/latest/source/api/index.html),
 hosted on [Read The Docs](https://readthedocs.org/).
 Additional supporting material can be found
 [here](https://github.com/pybamm-team/pybamm-supporting-material/).
@@ -100,7 +100,7 @@ PyBaMM uses [CalVer](https://calver.org/), which means that we make new releases
 
 PyBaMM is available on GNU/Linux, MacOS and Windows.
 We strongly recommend to install PyBaMM within a python virtual environment, in order not to alter any distribution python files.
-For instructions on how to create a virtual environment for PyBaMM, see [the documentation](https://pybamm.readthedocs.io/en/latest/source/user_guide/installation/GNU-linux.html#user-install).
+For instructions on how to create a virtual environment for PyBaMM, see [the documentation](https://docs.pybamm.org/en/latest/source/user_guide/installation/GNU-linux.html#user-install).
 
 ### Using pip
 

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
@@ -16,4 +16,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

docs/conf.py

@@ -53,6 +53,9 @@
     "sphinx_extend_parent",
     "sphinx_inline_tabs",
     "sphinxcontrib.bibtex",
+    "nbsphinx",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "sphinx_gallery.load_style",
 ]
 
 # -- sphinxcontrib-bibtex configuration --------------------------------------
@@ -92,10 +95,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".ipynb_checkpoints"]
 
 # Suppress warnings generated if footnotes are not references in a docstring
 # suppress_warnings = ["ref.footnote"]
@@ -138,10 +138,6 @@
     ],
     "collapse_navigation": True,
     "external_links": [
-        {
-            "name": "Examples",
-            "url": "https://github.com/pybamm-team/PyBaMM/tree/develop/examples",
-        },
         {
             "name": "Contributing",
             "url": "https://github.com/pybamm-team/PyBaMM/tree/develop/CONTRIBUTING.md",
@@ -156,6 +152,8 @@
     # for dark mode toggle, version switcher, and social media links
     "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
     "use_edit_page_button": True,
+    "pygment_light_style": "xcode",
+    "pygment_dark_style": "monokai",
 }
 
 html_title = "%s v%s Manual" % (project, version)
@@ -262,9 +260,47 @@
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "numpy": ("https://numpy.org/doc/stable", None),
     "scipy": ("https://docs.scipy.org/doc/scipy", None),
-    "matplotlib": ("https://matplotlib.org", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
 }
 
+# -- nbsphinx configuration options ------------------------------------------
+
+nbsphinx_prolog = r"""
+
+{% set github_docname =
+'github/pybamm-team/pybamm/blob/develop/docs/' +
+env.doc2path(env.docname, base=None) %}
+
+{% set readthedocs_download_url =
+'https://docs.pybamm.org/en/latest/' %}
+
+{% set doc_path = env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition tip">
+        <p class="admonition-title">
+            Tip
+        </p>
+        <p>
+            An interactive online version of this notebook is available, which can be
+            accessed via
+            <a href="https://colab.research.google.com/{{ github_docname | e }}" 
+            target="_blank">
+            <img src="https://colab.research.google.com/assets/colab-badge.svg"
+            alt="Open this notebook in Google Colab"/></a>
+        </p>
+            <hr>
+        <p>
+            Alternatively, you may
+            <a href="{{ readthedocs_download_url | e }}{{ doc_path | e }}"
+            target="_blank" download>
+            download this notebook</a> and run it offline.
+        </p>
+    </div>
+
+"""
+
 # -- Jinja templating --------------------------------------------------------
 # Credit to: https://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
 

docs/index.rst

@@ -15,6 +15,7 @@ PyBaMM documentation
 
    User Guide <source/user_guide/index>
    source/api/index
+   source/examples/index
 
 **Version**: |version|
 
@@ -68,7 +69,7 @@ explore the effect of different battery designs and modeling assumptions under a
 
       +++
 
-      .. button-link:: https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks
+      .. button-ref:: source/examples/index
          :expand:
          :color: secondary
          :click-parent:

docs/requirements.txt

@@ -25,3 +25,8 @@ sphinx-copybutton
 myst-parser
 sphinx-inline-tabs
 sphinxcontrib-bibtex
+nbsphinx
+ipython
+ipykernel
+ipywidgets
+sphinx-gallery

docs/source/api/index.rst

@@ -11,7 +11,7 @@ API documentation
 
 This reference manual details functions, modules, and objects
 included in PyBaMM, describing what they are and what they do.
-For a high-level introduction to PyBaMM, see the :ref:`user guide <user_guide>`.
+For a high-level introduction to PyBaMM, see the :ref:`user guide <user_guide>` and the :ref:`examples <examples>`.
 
 .. toctree::
    :maxdepth: 2

docs/source/api/models/index.rst

@@ -5,7 +5,7 @@ Below is an overview of all the battery models included in PyBaMM.
 Each of the pre-built models contains a reference to the paper in which it is derived.
 
 The models can be customised using the `options` dictionary defined in the :class:`pybamm.BaseBatteryModel` (which also provides information on which options and models are compatible)
-Visit our `examples page <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks/models>`_
+Visit our `examples page <https://github.com/pybamm-team/PyBaMM/tree/develop/docs/source/examples/notebooks/models>`_
 to see how these models can be solved, and compared, using PyBaMM.
 
 .. toctree::