Documentation

The home for our user-facing documentation and related infrastructure. If you need to make updates to our external docs site, you're in the right place.

Prerequisites

We use Quarto to develop our docs site, an open-source docs framework based on Pandoc that supports multiple input formats such as Quarto Markdown, Jupyter notebooks, and Markdown.

You need:

• Quarto CLI
• The Quarto extension for your IDE, such as VS Code

How our docs site is sourced

site
├── _source
|   └── validmind-python
|       └── docs
|           └── _build
|               └── validmind
|                   └── *.html, *.js
├── guide
│   └── *.qmd, *.svg, *.png
├── notebooks
|   ├── how_to
|   |   └── *.ipynb
│   └── *.ipynb
├── _quarto.yml
└── index.qmd

_source/ ... validmind/ — Built Developer Framework API docs

guide/ — Core docs sourced in Quarto Markdown

notebooks/ — Jyupiter notebooks copied from validmind-python/notebooks or Google Drive

_quarto.yml — Rendering options for the site, including navigation, search, footer, and more

index.qmd — Main landing page sourced in Quarto Markdown and HTML

Preview the docs site

cd site
quarto preview

Update files sourced from other repos

cd site
make get-source

Important: This action doesn't copy the Jupyter notebooks sourced from Google Drive. You need to update these notebooks manually.

Generate the docs site

Including fetching the source from other repos:

cd site
make docs-site

Just render the site:

cd site
quarto render

The rendered static HTML output lives in:

site
└── _site ...
    └── *.html, *.css, *.png, *.js ...

Deploy the production docs site

Automatically from the prod branch: merge a commit into the branch with the latest changes from main.

Manually from the main or prod branches:

make deploy-prod

Deploy the docs demo site

Automatically from the docs-demo branch: merge a commit into the branch, e.g. with the files you want to deploy.

Manually from the docs-demo branch:

make deploy-demo