Skip to main content

Contribute Documentation

The docs directory contains Documentation and API Reference.

Documentation is built using Quarto and Docusaurus 2.

API Reference are largely autogenerated by sphinx from the code and are hosted by Read the Docs. For that reason, we ask that you add good documentation to all classes and methods.

Similar to linting, we recognize documentation can be annoying. If you do not want to do it, please contact a project maintainer, and they can help you with it. We do not want this to be a blocker for good code getting contributed.

Build Documentation Locally​

Install dependencies​

  • Quarto - package that converts Jupyter notebooks (.ipynb files) into mdx files for serving in Docusaurus.
  • poetry install from the monorepo root

Building​

In the following commands, the prefix api_ indicates that those are operations for the API Reference.

Before building the documentation, it is always a good idea to clean the build directory:

make docs_clean
make api_docs_clean

Next, you can build the documentation as outlined below:

make docs_build
make api_docs_build

Finally, run the link checker to ensure all links are valid:

make docs_linkcheck
make api_docs_linkcheck

Linting and Formatting​

The docs are linted from the monorepo root. To lint the docs, run the following from there:

poetry install --with lint,typing
make lint

If you have formatting-related errors, you can fix them automatically with:

make format

Verify Documentation changes​

After pushing documentation changes to the repository, you can preview and verify that the changes are what you wanted by clicking the View deployment or Visit Preview buttons on the pull request Conversation page. This will take you to a preview of the documentation changes. This preview is created by Vercel.