Documentation Contribution Guide
Building Documentation Locally
You can build and serve the documentation locally by following these steps:
We recommended using a virtual environment for your project to keep your packages contained. See venv.
Prerequisites
- Install Quarto:
- Visit the Quarto download page.
- Navigate to the Pre-release tab and download the latest version
- Ensure you install version
1.5.23or higher.
Installation
From the project root directory, install the necessary Python packages:
Building the Documentation
To build the documentation locally, run the following command from the project root directory:
Optionally, you can pass the --force flag to clean up all temporary files and generate the documentation from scratch:
Serving the documentation
Once the build is complete, please run the following command to serve the docs:
This will spin up a server at port 8000, which you can access by visiting http://localhost:8000 in your browser.
Build with Dev Containers
If you prefer to use a containerized development environment, you can build and test the documentation using Dev Containers.
Setting up Dev Containers
- Install VSCode if you haven’t already.
- Open the project in VSCode.
- Press
Ctrl+Shift+P(orCmd+Shift+Pon Mac) and selectDev Containers: Reopen in Container.
This will open the project in a Dev Container with all the required dependencies pre-installed.
Building and serving in the container
Once your project is open in the Dev Container:
-
Open a terminal in VSCode and install the project with docs dependencies:
-
Build the documentation:
-
Serve the documentation:
The documentation will be accessible at http://localhost:8000 in your browser.
Handling updates or changes
For any changes to be reflected in the documentation, you will need to:
- Stop the running server
- Run the build command again
- Start the server again
When switching branches or making major changes to the documentation structure, you might occasionally notice deleted files still appearing or changes not showing up properly. This happens due to cached build files. In such cases, running the commands with the --force flag will clear the cache and rebuild everything from scratch:
Adding Notebooks to the Website
When you want to add a new Jupyter notebook and have it rendered in the documentation, you need to follow specific guidelines to ensure proper integration with the website.
Please refer to this guideline for more details.
Before Making a Pull Request
To maintain code quality and consistency, we use pre-commit hooks that automatically run checks like linting, formatting, and other validations before each commit. It’s important to have these properly set up in your development environment before you start committing changes.
If you skip this setup, your pull request’s CI checks may fail, and you’ll need to fix issues and update your PR later — so it’s highly recommended to get everything configured upfront.
For more information on setting up the development environment, refer to this page.
Setting up Pre-commit Hooks
From the project root, run the following command to install the development dependencies and set up the pre-commit hooks:
This ensures that every time you run git commit, a series of checks will automatically be executed.
Documentation Contribution Guide
Building Documentation Locally
You can build and serve the documentation locally by following these steps:
We recommended using a virtual environment for your project to keep your packages contained. See venv.
Prerequisites
- Install Quarto:
- Visit the Quarto download page.
- Navigate to the Pre-release tab and download the latest version
- Ensure you install version
1.5.23or higher.
Installation
From the project root directory, install the necessary Python packages:
Building the Documentation
To build the documentation locally, run the following command from the project root directory:
Optionally, you can pass the --force flag to clean up all temporary files and generate the documentation from scratch:
Serving the documentation
Once the build is complete, please run the following command to serve the docs:
This will spin up a server at port 8000, which you can access by visiting http://localhost:8000 in your browser.
Build with Dev Containers
If you prefer to use a containerized development environment, you can build and test the documentation using Dev Containers.
Setting up Dev Containers
- Install VSCode if you haven’t already.
- Open the project in VSCode.
- Press
Ctrl+Shift+P(orCmd+Shift+Pon Mac) and selectDev Containers: Reopen in Container.
This will open the project in a Dev Container with all the required dependencies pre-installed.
Building and serving in the container
Once your project is open in the Dev Container:
-
Open a terminal in VSCode and install the project with docs dependencies:
-
Build the documentation:
-
Serve the documentation:
The documentation will be accessible at http://localhost:8000 in your browser.
Handling updates or changes
For any changes to be reflected in the documentation, you will need to:
- Stop the running server
- Run the build command again
- Start the server again
When switching branches or making major changes to the documentation structure, you might occasionally notice deleted files still appearing or changes not showing up properly. This happens due to cached build files. In such cases, running the commands with the --force flag will clear the cache and rebuild everything from scratch:
Adding Notebooks to the Website
When you want to add a new Jupyter notebook and have it rendered in the documentation, you need to follow specific guidelines to ensure proper integration with the website.
Please refer to this guideline for more details.
Before Making a Pull Request
To maintain code quality and consistency, we use pre-commit hooks that automatically run checks like linting, formatting, and other validations before each commit. It’s important to have these properly set up in your development environment before you start committing changes.
If you skip this setup, your pull request’s CI checks may fail, and you’ll need to fix issues and update your PR later — so it’s highly recommended to get everything configured upfront.
For more information on setting up the development environment, refer to this page.
Setting up Pre-commit Hooks
From the project root, run the following command to install the development dependencies and set up the pre-commit hooks:
This ensures that every time you run git commit, a series of checks will automatically be executed.