Hi there! This is the fifth 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 working with physics-based battery models.
A summary of the tasks I completed
I am continuing to work on adding quality-of-life improvements to the documentation and also to refine it, i.e., to consolidate all its parts in one place so that it is more readable and maintainable for core users and developers respectively.
With the main requirements of my project and all of the stretch goals associated with it complete, my project is nearing its twilight phase. Therefore, we have decided to create a template for PyBaMM-based projects that will be available for the battery community to make the process of packaging and distributing code much easier, more details below:
- Algolia docsearch (pybamm-team/PyBaMM #3159)
- Generate teams (pybamm-team/pybamm.org #31)
- Accessibility improvements (pybamm-team/pybamm.org #32)
- Generate teams in the CI (pybamm-team/pybamm.org #34)
Some other, shorter PRs that I opened for minor fixes and improvements:
- Configure versions.json and remove the version switcher dropdown (pybamm-team/PyBaMM #3108)
- Ensure setup-python outputs are always included in
noxcache keys (pybamm-team/PyBaMM #3157) - Restructure notebook galleries (pybamm-team/PyBaMM #3167)
- Enable downloadable PDF, EPUB, and zipped HTML formats on Read the Docs (pybamm-team/PyBaMM #3182)
- Add docstrings for
noxsessions (pybamm-team/PyBaMM #3183)
The website is at the verge of its completion at the time of writing, and will be showcased officially to the battery community soon!
Algolia DocSearch v3
We recently applied for Algolia's search-as-you-type service that is available for eligible open-source projects and technical blogs. It replaces the older, slower search available via the PyData Sphinx Theme and Sphinx.
Try it out on the latest PyBaMM documentation website!
Generating a page highlighting the team members and contributors
Truly, recognising the work of everyone who contributed to PyBaMM is the insignia of legends.
I added a teams page on the PyBaMM website at https://pybamm.org/teams/. It lists the maintainers, emeritus maintainers, maintainer trainees, and contributors one after the other. The scripts/generate_teams.py file, also linked against the target make teams, when run, gets data from the GitHub API and adds details about the teams in their respective HTML pages.
I also added a simple workflow to accompany this script; it runs this script set according to a CRON job weekly with GitHub Actions, automatically creates a pull request if there are changes, and asks for reviews from the four maintainers of the repository.
Note: PyBaMM follows the all-contributors specification to recognise contributions beyond code (bug reports, documentation, fiscal sponsorships, et cetera). To see the full list of contributors, see the Contributors section in the PyBaMM repository README.
Setting up a new project: pybamm-cookiecutter
The mentors and I have decided to implement a standardised template for projects that use PyBaMM. This template is intended to be used with projects that use PyBaMM and serve as an educational resource as well.
Once completed, this template can be used with standard templating engines such as cookiecutter and cruft, and possibly copier in the future. This way, people can distribute Jupyter notebooks as examples, utility functions and custom source code that build upon PyBaMM as a dependency, scripts for code releases for a preprint or a paper that uses PyBaMM in a collaborative academic setting, and much more.
The build-backends that are to be supported are hatch, flit. Support for the backends setuptools621 and setuptools is also planned. The repository will remain opinionated and will also support adding custom tools such as the PyBaMM's favourite pre-commit hooks, such as ruff, black, and nbQA.
Optionally, users of the template will also be able to load data through python-dotenv and a .env file in the root directory that will containing the path to data-related files, which will serve the purpose of keeping code and data separate.
Last but surely not the least, this will provide a unified method for adding third-party parameter sets through a combination of a parameters/ folder and entry points in pyproject.toml.
Please feel free to comment on the issue thread in the pybamm-cookiecutter repository and share your thoughts. Keep watching this space for more updates!
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)