Documentation

​

How to get a notebook rendered on the website

See here for instructions on how to get a notebook in the notebook directory rendered on the website.

​

Build documentation locally

Follow these steps to build and serve the documentation on your local machine:

1. Install Node.js:

   • Download and install Node.js

2. Install Quarto:

   • Visit the Quarto download page.
   • Click on the Pre-release tab and download the latest version of Quarto.
   • Ensure you install version 1.5.23 or higher.

3. Install Required Python Packages:

   • From the project root directory, install the necessary Python packages by running:

     pip install -e ".[docs]"
     

4. Build and Serve the Documentation:

   • To build and serve the documentation locally, run the following command from the project root directory:

     ./scripts/docs_serve.sh
     

   • Optionally, you can pass the --force flag to clean up all temporary files and generate the documentation from scratch:

     ./scripts/docs_serve.sh --force
     

5. Handling Updates or Changes:

   • Whenever you update the documentation, stop the server and re-run the ./scripts/docs_serve.sh command to serve the docs with the latest changes and view them live.

   • If deleted files are still displayed, it indicates cached or temporary files may be causing issues. To resolve this, use the --force flag to clean the build directory and regenerate the documentation.

By following these steps, you can build, serve, and update the documentation locally.

​

Build with Dev Containers

To build and test documentation using Dev Containers, open the project using VSCode, press Ctrl+Shift+P and select Dev Containers: Reopen in Container.

This will open the project in a Dev Container with all the required dependencies installed.

Build and Serve the Documentation:

• Open a terminal and run the following commands to build and serve the documentation:

  pip install -e ".[docs]"
  ./scripts/docs_serve.sh
  

• Optionally, you can pass the --force flag to clean up all temporary files and generate the documentation from scratch:

  pip install -e ".[docs]"
  ./scripts/docs_serve.sh --force
  

Once done you should be able to access the documentation at http://localhost:3000/.

Handling Updates or Changes:

• Whenever you update the documentation, stop the server and re-run the ./scripts/docs_serve.sh command to serve the docs with the latest changes and view them live.

• If deleted files are still displayed, it indicates cached or temporary files may be causing issues. To resolve this, use the --force flag to clean the build directory and regenerate the documentation.