Merge pull request #2618 from pybamm-team/pydata-theme

Change docs to use Pydata theme

CHANGELOG.md

@@ -2,8 +2,10 @@
 
 ## Features
 
-- Steps in `Experiment` can now be tagged and cycle numbers be searched based on those tags ([#2593](https://github.com/pybamm-team/PyBaMM/pull/2593)).
+- Changed linting from `flake8` to `ruff` ([#2630](https://github.com/pybamm-team/PyBaMM/pull/2630)).
+- Changed docs theme to pydata theme and start to improve docs in general ([#2618](https://github.com/pybamm-team/PyBaMM/pull/2618)).
 - New `contact resistance` option, new parameter `Contact resistance [Ohm]` and new variable `Contact overpotential [V]` ([#2598](https://github.com/pybamm-team/PyBaMM/pull/2598)).
+- Steps in `Experiment` can now be tagged and cycle numbers be searched based on those tags ([#2593](https://github.com/pybamm-team/PyBaMM/pull/2593)).
 
 ## Bug fixes
 

README.md

@@ -45,7 +45,7 @@ sim.solve([0, 3600])  # solve for 1 hour
 sim.plot()
 ```
 
-or simulate an experiment such as CCCV:
+or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge:
 
 ```python3
 import pybamm

docs/conf.py

@@ -15,7 +15,6 @@
 import os
 import sys
 import pybamm
-import guzzle_sphinx_theme
 
 sys.path.insert(0, os.path.abspath("../"))
 
@@ -48,6 +47,8 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx_design",
+    "sphinx_copybutton",
 ]
 
 
@@ -88,44 +89,63 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-# html_theme = "sphinxdoc"
+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_static_path = ["source/_static"]
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+# Theme
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
+# pydata theme options (see
+# https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html# for more information)
+# mostly copied from numpy, scipy, pandas
+html_logo = "source/_static/pybamm_logo.png"
 
-# Guzzle theme
+html_theme_options = {
+    "logo": {
+        "image_light": "pybamm_logo.png",
+        "image_dark": "pybamm_logo.png",
+    },
+    "github_url": "https://github.com/pybamm-team/pybamm",
+    "twitter_url": "https://twitter.com/pybamm_",
+    "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",
+        },
+    ],
+    # Add light/dark mode and documentation version switcher:
+    # "navbar_end": ["theme-switcher", "version-switcher", "navbar-icon-links"],
+    # "switcher": {
+    #     "version_match": switcher_version,
+    #     "json_url": "https://numpy.org/doc/_static/versions.json",
+    # },
+    "use_edit_page_button": True,
+}
 
-html_theme_path = guzzle_sphinx_theme.html_theme_path()
-html_theme = "guzzle_sphinx_theme"
+html_title = "%s v%s Manual" % (project, version)
+html_last_updated_fmt = "%b %d, %Y"
+html_css_files = ["pybamm.css"]
+html_context = {"default_mode": "light"}
+html_use_modindex = True
+html_copy_source = False
+html_domain_indices = False
+html_file_suffix = ".html"
 
-# Register the theme as an extension to generate a sitemap.xml
-extensions.append("guzzle_sphinx_theme")
+htmlhelp_basename = "pybamm"
 
-# Guzzle theme options (see theme.conf for more information)
-html_theme_options = {
-    # Set the name of the project to appear in the sidebar
-    "project_nav_name": project
+html_sidebars = {"**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"]}
+
+# For edit button
+html_context = {
+    "github_user": "pybamm-team",
+    "github_repo": "pybamm",
+    "github_version": "develop",
+    "doc_path": "docs/",
 }
 
 
@@ -210,7 +230,7 @@
     "python": ("https://docs.python.org/3/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
     "numpy": ("https://numpy.org/doc/stable", None),
-    # "scipy": ("http://docs.scipy.org/doc/scipy/reference", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
     "matplotlib": ("https://matplotlib.org", None),
 }
 
@@ -235,6 +255,8 @@ def setup(app):
 
 
 # Context for Jinja Templates
-html_context = {
-    "parameter_sets": pybamm.parameter_sets,
-}
+html_context.update(
+    {
+        "parameter_sets": pybamm.parameter_sets,
+    }
+)

docs/index.rst

@@ -1,101 +1,117 @@
 .. Root of all pybamm docs
 
-.. _GitHub: https://github.com/pybamm-team/PyBaMM
+.. Remove the right side-bar for the home page
 
-Welcome to PyBaMM's documentation!
-==================================
+:html_theme.sidebar_secondary.remove:
 
-Python Battery Mathematical Modelling (**PyBAMM**) solves continuum models for
-batteries, using both numerical methods and asymptotic analysis.
+####################
+PyBaMM documentation
+####################
 
-PyBaMM is hosted on GitHub_. This page provides the *API*, or *developer
-documentation* for ``pybamm``.
+.. This TOC defines what goes in the top navbar
+.. toctree::
+   :maxdepth: 1
+   :hidden:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   source/user_guide/index
+   source/api/index
 
-Quickstart
-=========================
-PyBaMM is available on GNU/Linux, MacOS and Windows.
+**Version**: |version|
 
-Using pip
-----------
+.. **Download documentation**:
+.. `PDF Version <https://numpy.org/doc/stable/numpy-user.pdf>`_ |
+.. `Historical versions of documentation <https://numpy.org/doc/>`_
+   
+**Useful links**:
+`Project Home Page <https://pybamm.org>`_ |
+`Installation <source/user_guide/installation/index.html>`_ |
+`Source Repository <https://github.com/pybamm-team/pybamm>`_ |
+`Issue Tracker <https://github.com/pybamm-team/pybamm/issues>`_ |
+`Discussions <https://github.com/pybamm-team/pybamm/discussions>`_
 
-GNU/Linux and Windows
-~~~~~~~~~~~~~~~~~~~~~~
+PyBaMM (Python Battery Mathematical Modelling) is an open-source battery simulation package
+written in Python. Our mission is to accelerate battery modelling research by
+providing open-source tools for multi-institutional, interdisciplinary collaboration. 
+Broadly, PyBaMM consists of
 
-.. code:: bash
+#. a framework for writing and solving systems of differential equations,
+#. a library of battery models and parameters, and
+#. specialized tools for simulating battery-specific experiments and visualizing the results.
 
-   pip install pybamm
+Together, these enable flexible model definitions and fast battery simulations, allowing users to
+explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.
 
-macOS
-~~~~~~~~~~~~~~~~~~~~~~
+.. grid:: 2
 
-.. code:: bash
+   .. grid-item-card::
+      :img-top: source/_static/index-images/getting_started.svg
 
-   brew install sundials && pip install pybamm
+      User Guide
+      ^^^^^^^^^^
 
-Using conda
--------------
-PyBaMM is available as a conda package through the conda-forge channel.
+      The user guide is the best place to start learning PyBaMM. It contains an installation
+      guide, an introduction to the main concepts and links to additional tutorials.
 
-.. code:: bash
+      +++
 
-   conda install -c conda-forge pybamm
+      .. button-ref:: source/user_guide/index
+         :expand:
+         :color: secondary
+         :click-parent:
 
-Optional solvers
------------------
-Following GNU/Linux and macOS solvers are optionally available:
+         To the user guide
+
+   .. grid-item-card::
+      :img-top: source/_static/index-images/examples.svg
 
-*  `scikits.odes <https://scikits-odes.readthedocs.io/en/latest/>`_ -based solver, see `Optional - scikits.odes solver <https://pybamm.readthedocs.io/en/latest/install/GNU-linux.html#optional-scikits-odes-solver>`_.
-*  `jax <https://jax.readthedocs.io/en/latest/notebooks/quickstart.html>`_ -based solver, see `Optional - JaxSolver <https://pybamm.readthedocs.io/en/latest/install/GNU-linux.html#optional-jaxsolver>`_.
+      Examples
+      ^^^^^^^^
 
-Installation
-============
+      Examples and tutorials can be viewed on the GitHub examples page,
+      which also provides a link to run them online through Google Colab.
 
-.. toctree::
-   :maxdepth: 1
+      +++
 
-   install/GNU-linux
-   install/windows
-   install/windows-wsl
-   install/install-from-source
+      .. button-link:: https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks
+         :expand:
+         :color: secondary
+         :click-parent:
 
-API documentation
-====================
+         To the examples
 
-.. module:: pybamm
+   .. grid-item-card::
+      :img-top: source/_static/index-images/api.svg
 
-.. toctree::
-   :maxdepth: 2
-
-   source/expression_tree/index
-   source/models/index
-   source/parameters/index
-   source/geometry/index
-   source/meshes/index
-   source/spatial_methods/index
-   source/solvers/index
-   source/experiments/index
-   source/simulation
-   source/plotting/index
-   source/util
-   source/callbacks
-   source/citations
-   source/batch_study
-
-Examples
-========
-
-Detailed examples can be viewed on the
-`GitHub examples page <https://github.com/pybamm-team/PyBaMM/tree/develop/examples/notebooks>`_,
-and run locally using ``jupyter notebook``, or online through
-`Google Colab <https://colab.research.google.com/github/pybamm-team/PyBaMM/blob/develop/>`_.
-
-Contributing
-============
-
-Contributions to PyBaMM and its development are welcome! If you have ideas for features, bug fixes, models, spatial methods, or solvers, we would love to hear from you.
-
-Before contributing, please read the `Contribution Guidelines <https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md>`_.
+      API Documentation
+      ^^^^^^^^^^^^^^^^^
+
+      The reference guide contains a detailed description of the functions,
+      modules, and objects included in PyBaMM. The reference describes how the
+      methods work and which parameters can be used.
+
+      +++
+
+      .. button-ref:: source/api/index
+         :expand:
+         :color: secondary
+         :click-parent:
+
+         To the API documentation
+
+   .. grid-item-card::
+      :img-top: source/_static/index-images/contributor.svg
+
+      Contributor's Guide
+      ^^^^^^^^^^^^^^^^^^^
+
+      Contributions to PyBaMM and its development are welcome! If you have ideas for
+      features, bug fixes, models, spatial methods, or solvers, we would love to hear from you.
+
+      +++
+
+      .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md
+         :expand:
+         :color: secondary
+         :click-parent:
+
+         To the contributor's guide

docs/requirements.txt

@@ -16,5 +16,7 @@ sympy >= 1.8
 # Should not be imported
 matplotlib >= 2.0
 #
-guzzle-sphinx-theme
 sphinx>4.0
+pydata-sphinx-theme
+sphinx_design
+sphinx-copybutton