Improving PyBaMM's documentation infrastructure â a Google Summer of Code (GSoC) 2023 project
Agriya Khetarpal
20312915002
University of Delhi
About PyBaMM đ
- Open-source battery modelling package for conducting experiments and simulations
- Written in Python, interfaces a
C++solver for ODEs and DAEs - Permissive BSD-3 Clause license
- Prevalent across battery science research, especially for the study of the effects of lithium-ion batteries
- Several common battery models implemented
The what, the why, and the where? đ
- Lack of a consolidated location for hosting project-specific information for PyBaMM
- Outdated website which is (was) difficult to navigate
- Project wiki, governance, example notebooks were scattered
What I did đ§âđģ
- New static website for PyBaMM based on a unified theme developed for larger, general-purpose Python packages:
NumPyandSciPy - Contains everything from the previous website + a newsroom + teams page + user guides + community pages: everything under one roof
- Improved documentation infrastructure on
https://docs.pybamm.org: multiple widgets and quality-of-life improvements (explained further!)
Documentation infrastructure improvements âŠī¸
- Goal: more maintainable documentation
- Make it easier to write new documentation while also keeping in mind the needs of the users
- Adding features by liasing with other popular projects in the Scientific Python ecosystem
- Benefits
- Easier-to-follow API documentation
- Integrated example notebooks
- Less breakage, more stability
Before...
...after
Automated references
Thumbnail galleries for example notebooks
Download and run notebooks at ease
Floating-window tooltips for x-references
Autogenerated inheritance diagrams
Integrating Algolia DocSearch: search-as-you-type
Improving the general infrastructure for the package đ§
- Improved continuous integration and continuous delivery pipelines
- In most cases, âĨ50% faster!
- Faster documentation builds
- Some parts of this area overlapped with my GSoC co-student Arjun
- Docker images for simplified installation
- PDFs of the documentation on every release
What's next? đŽ
- New template project:
pybamm-cookiecutter- Provide a standard, opinionated template for battery modelling projects
- Make using custom parameter sets easier
- Still a work in progress
- Nightly releases:
- Create a registry or a server where we upload binary distributions of PyBaMM every night with the latest changes
- Status: waiting on triage
Post GSoC đŖī¸
- We migrated PyBaMM to pyproject.toml
- New build format with more reliable installation
- Modern + up-to-date with the latest Scientific Python guidelines
- Enhanced notebook testing infrastructure
- Laid down basis for migration to pytest
- Parallel execution of notebooks â up to 5x faster based on empirical Amdahl's Law calculations, 2x faster on GitHub Actions CI runners
Post GSoC đ§âđ
- Recently appointed as a maintainer trainee (October 2023) with a progressive path to maintainer status
- I am now giving back to the community by helping triage issues and pull requests, performing code reviews, guiding new contributors, and more
- I plan to stay involved for a long time
Thank you!
To read more, please read my work product submission using the QR code below
Improving PyBaMM's documentation infrastructure â a Google Summer of Code (GSoC) 2023 project Agriya Khetarpal 20312915002 University of Delhi