Merge pull request #141 from pybop-team/15-create-documentation-for-p…

…ybop

Adds documentation site

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,39 @@
+name: Deploy Documentation
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+permissions:
+  contents: write # allow write access for docs deployment
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out PyBOP repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+    - 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 dependencies
+      run: |
+        python -m pip install --upgrade pip nox
+    - name: Using Python 3.11, build the docs
+      run: nox -s docs
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html
+        publish_branch: gh-pages

.github/workflows/scheduled_tests.yaml

@@ -33,7 +33,7 @@ jobs:
           python -m nox -s unit
           python -m nox -s notebooks
 
-    #M-series Mac Mini
+  #M-series Mac Mini
   build-apple-mseries:
     runs-on: [self-hosted, macOS, ARM64]
     env:

.gitignore

@@ -175,6 +175,9 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/examples/generated/
+docs/api/
+warnings.txt
 
 # PyBuilder
 .pybuilder/
@@ -306,4 +309,4 @@ $RECYCLE.BIN/
 .vscode/*
 
 # Output JSON files
-*fit_ecm_parameters.json
+**/fit_ecm_parameters.json

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Features
 
+- [#141](https://github.com/pybop-team/PyBOP/pull/141) - Adds documentation with Sphinx and PyData Sphinx Theme. Updates docstrings across package, relocates `costs` and `dataset` to top-level of package. Adds noxfile session and deployment workflow for docs.
 - [#131](https://github.com/pybop-team/PyBOP/issues/131) - Adds `SciPyDifferentialEvolution` optimiser, adds functionality for user-selectable maximum iteration limit to `SciPyMinimize`, `NLoptOptimize`, and `BaseOptimiser` classes.
 - [#107](https://github.com/pybop-team/PyBOP/issues/107) - Adds Equivalent Circuit Model (ECM) with examples, Import/Export parameter methods `ParameterSet.import_parameter` and `ParameterSet.export_parameters`, updates default FittingProblem.signal definition to `"Voltage [V]"`, and testing infrastructure
 - [#127](https://github.com/pybop-team/PyBOP/issues/127) - Adds Windows and macOS runners to the `test_on_push` action

CONTRIBUTING.md

@@ -1,8 +1,8 @@
-# Contributing to PyBOP
+# Contributing
 
 If you'd like to contribute to PyBOP, please have a look at the guidelines below.
 
-## Installation
+## Developer-Installation
 
 To install PyBOP for development purposes, which includes the testing and plotting dependencies, use the `[all]` flag as demonstrated below:
 
@@ -30,7 +30,7 @@ pip install pre-commit
 pre-commit install
 ```
 
-This would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using -
+This would run the checks every time a commit is created locally. The checks will only run on the files modified by that commit, but the checks can be triggered for all the files using,
 
 ```bash
 pre-commit run --all-files
@@ -47,7 +47,7 @@ We use [GIT](https://en.wikipedia.org/wiki/Git) and [GitHub](https://en.wikipedi
 1. Create an [issue](https://guides.github.com/features/issues/) where new proposals can be discussed before any coding is done.
 2. Create a [branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) of this repo (ideally on your own [fork](https://help.github.com/articles/fork-a-repo/)), where all changes will be made
 3. Download the source code onto your local system, by [cloning](https://help.github.com/articles/cloning-a-repository/) the repository (or your fork of the repository).
-4. [Install](Developer-Install) PyBOP with the developer options.
+4. [Install](#developer-installation) PyBOP with the developer options.
 5. [Test](#testing) if your installation worked: `$ pytest --unit -v`.
 
 You now have everything you need to start making changes!
@@ -82,7 +82,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://guides.github.com/features/issues/).
 
 When you commit your changes they will be checked against ruff automatically (see [Pre-commit checks](#pre-commit-checks)).
 
@@ -126,6 +126,16 @@ def plot_great_things(self, x, y, z):
 
 This allows people to (1) use PyBOP without ever importing Matplotlib and (2) configure Matplotlib's back-end in their scripts, which _must_ be done before e.g. `pyplot` is first imported.
 
+### Building documentation
+
+We use [Sphinx](http://www.sphinx-doc.org/en/stable/) to build our documentation. A nox session has been created to reduce the overhead when building the documentation locally. To run this session, type
+
+```bash
+nox -s docs
+```
+
+This will build the docs using sphinx-autobuild and render them in your browser.
+
 ## Testing
 
 All code requires testing. We use the [pytest](https://docs.pytest.org/en/) package for our tests. (These tests typically just check that the code runs without error, and so, are more _debugging_ than _testing_ in a strict sense. Nevertheless, they are very useful to have!)
@@ -283,7 +293,7 @@ Configuration files:
 setup.py
 ```
 
-Note that this file must be kept in sync with the version number in [pybop/**init**.py](pybop/__init__.py).
+Note that this file must be kept in sync with the version number in [pybop/**init**.py](https://github.com/pybop-team/PyBOP/blob/develop/pybop/__init__.py).
 
 ### Continuous Integration using GitHub actions
 
@@ -306,11 +316,10 @@ Code coverage (how much of our code is seen by the (Linux) unit tests) is tested
 
 GitHub does some magic with particular filenames. In particular:
 
-- The first page people see when they go to [our GitHub page](https://github.com/pybop-team/PyBOP) 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 PyBOP 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/pybop-team/PyBOP) displays the contents of [README.md](https://github.com/pybop-team/PyBOP/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 PyBOP is stored in [LICENSE](https://github.com/pybop-team/PyBOP/blob/develop/LICENSE), and [automatically](https://help.github.com/articles/adding-a-license-to-a-repository/) linked to by GitHub.
+- This file, [CONTRIBUTING.md](https://github.com/pybop-team/PyBOP/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
 
-This CONTRIBUTING.md file, along with large sections of the code infrastructure,
-was copied from the excellent [Pints repo](https://github.com/pints-team/pints), and [PyBaMM repo](https://github.com/pybamm-team/PyBaMM)
+This CONTRIBUTING.md file, along with large sections of the code infrastructure, was copied from the excellent [Pints repo](https://github.com/pints-team/pints), and [PyBaMM repo](https://github.com/pybamm-team/PyBaMM)

docs/Contributing.md

@@ -0,0 +1,8 @@
+---
+myst:
+  html_meta:
+    "description lang=en": |
+      Contributing docs..
+---
+
+```{include} ../CONTRIBUTING.md

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

docs/_extension/gallery_directive.py

@@ -0,0 +1,145 @@
+"""A directive to generate a gallery of images from structured data.
+
+Generating a gallery of images that are all the same size is a common
+pattern in documentation, and this can be cumbersome if the gallery is
+generated programmatically. This directive wraps this particular use-case
+in a helper-directive to generate it with a single YAML configuration file.
+
+It currently exists for maintainers of the pydata-sphinx-theme,
+but might be abstracted into a standalone package if it proves useful.
+
+Credit: PyData Sphinx Theme
+"""
+from pathlib import Path
+from typing import Any, Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from yaml import safe_load
+
+logger = logging.getLogger(__name__)
+
+
+TEMPLATE_GRID = """
+`````{{grid}} {columns}
+{options}
+
+{content}
+
+`````
+"""
+
+GRID_CARD = """
+````{{grid-item-card}} {title}
+{options}
+
+{content}
+````
+"""
+
+
+class GalleryGridDirective(SphinxDirective):
+    """A directive to show a gallery of images and links in a Bootstrap grid.
+
+    The grid can be generated from a YAML file that contains a list of items, or
+    from the content of the directive (also formatted in YAML). Use the parameter
+    "class-card" to add an additional CSS class to all cards. When specifying the grid
+    items, you can use all parameters from "grid-item-card" directive to customize
+    individual cards + ["image", "header", "content", "title"].
+
+    Danger:
+        This directive can only be used in the context of a Myst documentation page as
+        the templates use Markdown flavored formatting.
+    """
+
+    name = "gallery-grid"
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {
+        # A class to be added to the resulting container
+        "grid-columns": directives.unchanged,
+        "class-container": directives.unchanged,
+        "class-card": directives.unchanged,
+    }
+
+    def run(self) -> List[nodes.Node]:
+        """Create the gallery grid."""
+        if self.arguments:
+            # If an argument is given, assume it's a path to a YAML file
+            # Parse it and load it into the directive content
+            path_data_rel = Path(self.arguments[0])
+            path_doc, _ = self.get_source_info()
+            path_doc = Path(path_doc).parent
+            path_data = (path_doc / path_data_rel).resolve()
+            if not path_data.exists():
+                logger.info(f"Could not find grid data at {path_data}.")
+                nodes.text("No grid data found at {path_data}.")
+                return
+            yaml_string = path_data.read_text()
+        else:
+            yaml_string = "\n".join(self.content)
+
+        # Use all the element with an img-bottom key as sites to show
+        # and generate a card item for each of them
+        grid_items = []
+        for item in safe_load(yaml_string):
+            # remove parameters that are not needed for the card options
+            title = item.pop("title", "")
+
+            # build the content of the card using some extra parameters
+            header = f"{item.pop('header')}  \n^^^  \n" if "header" in item else ""
+            image = f"![image]({item.pop('image')})  \n" if "image" in item else ""
+            content = f"{item.pop('content')}  \n" if "content" in item else ""
+
+            # optional parameter that influence all cards
+            if "class-card" in self.options:
+                item["class-card"] = self.options["class-card"]
+
+            loc_options_str = "\n".join(f":{k}: {v}" for k, v in item.items()) + "  \n"
+
+            card = GRID_CARD.format(
+                options=loc_options_str, content=header + image + content, title=title
+            )
+            grid_items.append(card)
+
+        # Parse the template with Sphinx Design to create an output container
+        # Prep the options for the template grid
+        class_ = "gallery-directive" + f' {self.options.get("class-container", "")}'
+        options = {"gutter": 2, "class-container": class_}
+        options_str = "\n".join(f":{k}: {v}" for k, v in options.items())
+
+        # Create the directive string for the grid
+        grid_directive = TEMPLATE_GRID.format(
+            columns=self.options.get("grid-columns", "1 2 3 4"),
+            options=options_str,
+            content="\n".join(grid_items),
+        )
+
+        # Parse content as a directive so Sphinx Design processes it
+        container = nodes.container()
+        self.state.nested_parse([grid_directive], 0, container)
+
+        # Sphinx Design outputs a container too, so just use that
+        return [container.children[0]]
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+
+    Returns:
+        the 2 parallel parameters set to ``True``.
+    """
+    app.add_directive("gallery-grid", GalleryGridDirective)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/_templates/autoapi/index.rst

@@ -0,0 +1,18 @@
+.. _api-reference:
+
+API Reference
+=============
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 2
+
+   {% for page in pages %}
+   {% if page.top_level_object and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_