Background
bdpy is distributed on PyPI, but there is virtually no official documentation that users or contributors can refer to. The README only covers installation and a brief introduction; to understand the API or usage of individual modules (bdata, dataform, dataset, ml, mri, recon, ...), one has to read the source directly.
This creates several problems:
- High barrier to entry for new users
- Public API boundaries are not visible from outside, making it hard to contribute
- API changes across releases are difficult to communicate to users
Proposal
Build an official documentation site and publish it on GitHub Pages.
Proposed direction:
- API reference: Auto-generate public API docs from docstrings for each module. Existing docstrings follow NumPy style, so the toolchain should respect that.
- User guide / tutorials: Provide hand-written pages explaining core concepts (e.g. BData) and typical workflows.
- Auto-deploy: GitHub Actions publishes the site automatically on every push to
main.
Candidate toolchain (open to discussion):
- Static site generator: MkDocs + Material theme
- API generation: mkdocstrings (Python handler, NumPy style)
- CI/CD: GitHub Actions deploying to the
gh-pages branch
Sphinx is also a viable option, but MkDocs is preferred for its Markdown-based workflow, lower maintenance overhead, and lower barrier for contributors.
The existing docs/ directory contains a mostly empty Jekyll setup; rather than migrating it, starting fresh with a new structure seems cleaner.
Open Questions
- Opinions on toolchain choices (MkDocs vs Sphinx, theme, etc.) are welcome
- Whether to include
examples/*.ipynb in the site (tentatively out of scope for now)
Background
bdpy is distributed on PyPI, but there is virtually no official documentation that users or contributors can refer to. The README only covers installation and a brief introduction; to understand the API or usage of individual modules (
bdata,dataform,dataset,ml,mri,recon, ...), one has to read the source directly.This creates several problems:
Proposal
Build an official documentation site and publish it on GitHub Pages.
Proposed direction:
main.Candidate toolchain (open to discussion):
gh-pagesbranchSphinx is also a viable option, but MkDocs is preferred for its Markdown-based workflow, lower maintenance overhead, and lower barrier for contributors.
The existing
docs/directory contains a mostly empty Jekyll setup; rather than migrating it, starting fresh with a new structure seems cleaner.Open Questions
examples/*.ipynbin the site (tentatively out of scope for now)