Updating Project Documentation¶
LineaPy's project documentation is built with Material for MkDocs and deployed with Netlify.
Ensure that you have the requirements needed to build docs installed.
pip install -r requirements.txt from the
To add or update project documentation, take the following steps:
Add or update a Markdown file in
docs/folder. Check existing files or this reference for available features for technical writing.
navsection to surface the new/updated page. For instance, to add a new page under
nav: ... - Concepts: - Artifact: concepts/artifact.md - Artifact Store: concepts/artifact-store.md ... - New Page Title: concepts/new-page.md
Preview the update by starting a built-in dev-server:
# Run from docs/ mkdocs serve
Once satisfied with the change(s), open a PR.
Updating API Reference¶
For code documentation, first add or update docstrings using the NumPy style.
Docstrings with a different style (e.g., Google) may not render properly.
# Run from docs/ python gen_ref_pages.py
This will automatically generate or update Markdown file(s) for API reference.
Finally, open a PR with the changes.
To effectively manage different versions of documentation, the project limits publication capacity to a few select members. Please contact the LineaPy core team on Slack for relevant questions or requests.
LineaPy keeps a separate branch for each version of the package (e.g.,
This means each version’s documentation should be built from its own branch,
which makes sense because the
main branch may include changes that are not yet
ready for public release and use.
Accordingly, to build/update documentation for a particular version, run the following
on the corresponding version branch (e.g.,
# Run from docs/ mike deploy --push <version_number>
# Run from docs/ mike deploy --push --update-aliases <version_number> latest
<version_number> is formatted
0.2) as defined in
mike to build and maintain versioned documentation.
Specifically, it compiles different versions of the documentation into static files and commits them
gh-pages branch, which is continuously deployed by Netlify.