Skip to content

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 docs/ subdirectory.


To add or update project documentation, take the following steps:

  1. Add or update a Markdown file in docs/ folder. Check existing files or this reference for available features for technical writing.

  2. Update mkdocs.yml file's nav section to surface the new/updated page. For instance, to add a new page under Concepts section:

      - Concepts:
        - Artifact: concepts/
        - Artifact Store: concepts/
        - New Page Title: concepts/
  3. Preview the update by starting a built-in dev-server:

    # Run from docs/
    mkdocs serve
  4. 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.

Then, run:

# Run from docs/

This will automatically generate or update Markdown file(s) for API reference.

Finally, open a PR with the changes.

Publishing Updates


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., v0.2.x). 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., v0.2.x):

# Run from docs/
mike deploy --push <version_number>
# Run from docs/
mike deploy --push --update-aliases <version_number> latest

where <version_number> is formatted <major>.<minor> (e.g., 0.2) as defined in semantic versioning.


LineaPy uses mike to build and maintain versioned documentation. Specifically, it compiles different versions of the documentation into static files and commits them to the gh-pages branch, which is continuously deployed by Netlify.

Was this helpful?

Help us improve docs with your feedback!