Hi there! This is the third blog in a series of seven blogs that document my journey of my Google Summer of Code project under the NumFOCUS umbrella organisation where I aim to improve the documentation infrastructure for PyBaMM, a Python package for physics-based battery models.
A summary of the tasks I completed
With my GSoC project now in full swing and the website almost complete, I ventured into the foray of improving the documentation infrastructure for PyBaMM as well. You may read the API documentation and the user guide for getting started with PyBaMM at https://pybamm.readthedocs.io.
In these weeks, I opened many issues and PRs, listed as follows. These involved working not only with the documentation but other infrastructure-related quality of life improvements too!
- Restructure pages on the navigation bar and reformat contents (pybamm-team/pybamm.org #22)
- Reformat news to be single-page only (pybamm-team/pybamm.org #24)
- Add inline-tabs for Sphinx docs (pybamm-team/PyBaMM #3022)
- Use
sphinxcontrib-bibtexfor citing references in docs (pybamm-team/PyBaMM #3034) - Use
nbsphinxto embed Jupyter notebooks (pybamm-team/PyBaMM #3043) — this is currently not merged at the time of writing, though I am glad that I was able to make it work, since this was also one of the stretch goals of my project!
Other small contributions, related to repository infrastructure and maintenance:
- Use Python 3.11 for generating coverage in CI (pybamm-team/PyBaMM #3016)
- Remove backport
importlib_metadatafrom required dependencies (pybamm-team/PyBaMM #3050) - [Bug]: Conversion to scalars for arrays with ndim>0: NumPy 1.25 deprecation (Python 3.9–3.11)(pybamm-team/PyBaMM #3052) and its corresponding PR: Extract single element from np.ndarray when converting to scalar (pybamm-team/PyBaMM #3055)
Inline-tabs for Sphinx
This was a short PR to add the sphinx-inline-tabs extension. It removes redundancy for code blocks and those sections across the documentation and makes them much neater than before to the users' eyes:
You may view other examples of the extension in action on the PyBaMM Installation guide(s).
Keeping in-line textual citations in the documentation instead of hard-coding them
PyBaMM has a Citations class which reads information from a CITATIONS.bib file to register citations when users run a particular simulation and use certain models and solvers. Similarly, PyBaMM also offers a variety of common parameter sets referenced from values in papers over the past two decades of research and beyond. They were hard-coded in the docstrings for the model classes and the parameters.rst file, which made the citations prone to mistakes, spelling errors, and even validation errors in case a reference is not formatted correctly.
With the sphinxcontrib-bibtex extension; I was able to parse the CITATIONS.bib file to extract references from it, and then use the directives provided, such as :footcite:t: and .. footbibliography:: to display all references on a page programmatically. This serves the purpose of automation: I also added BibTeX references to some missing papers in this PR. An example of how the textual citation references look like is shown below.
More examples can be viewed at the Parameter Sets page in the PyBaMM documentation.
Galleries are always pretty, whether for Dadaist art... or for Jupyter notebooks
Insipired by the scikit-learn documentation, we decided to embed a gallery for PyBaMM's myriads of Jupyter notebooks that contain examples, beginner tutorials, advanced examples, model demonstrations, and more. This was particularly challenging because Sphinx still does not support relative links in the table of contents (the .. toctree:: directive), so the only options were to either use a cumbersome nbsphinx-link extension along with nbsphinx, or to move all the example notebooks from the examples/ folder in the root directory to the docs/source/examples/ directory. PyBaMM also uses Sphinx-based doctests, which also started failing due to errors in how the Markdown contents inside .ipynb notebooks are formatted—fixing them also took some time, since some notebooks had widgets, which caused a frozen module error with Python 3.11 and the doctests continued to run indefinitely in a PR for five hours and counting!
There were also other problems, such as the MathJax rendering for the model equations going haywire in many a location in likewise many a notebook when building the documentation—which were fixed via an agnostic syntax style for how equations are displayed, rather than KaTeX.
Watch out for the next blog to see the result and the forthcoming troubles (of course)!
Tasks to focus on in the coming weeks
- Further improvements to the documentation infrastructure in general
- Getting the revamped PyBaMM website (https://pybamm.org) ready to be shown to the world
- Embedding the PyBaMM example scripts in the documentation
Stay tuned
I will be posting these blogs fortnightly as a part of my GSoC project. Thoughts, comments, constructive criticism, and insights will be greatly appreciated. See you soon on the next one! For updates, please follow me on my social media handles:
Top comments (0)