Building and debugging docs

tl;dr: Once you’ve configured quartodoc in your _quarto.yml file, use the following commands to build and preview a documentation site.

quartodoc build: Create doc files

Automatically generate .qmd files with reference api documentation. This is written by default to the reference/ folder in your quarto project.

quartodoc build

If you are iterating on your docstrings while previewing your site with quarto preview, you will likely want to rebuild the doc pages automatically when docstrings change. The --watch flag does exactly this.

quartodoc build --watch

For more information on the quartodoc build command, use --help in the terminal like so:

quartodoc build --help
Usage: quartodoc build [OPTIONS]

  Generate API docs based on the given configuration file  (`./_quarto.yml` by
  default).

Options:
  --config TEXT  Change the path to the configuration file.  The default is
                 `./_quarto.yml`
  --filter TEXT  Specify the filter to select specific files. The default is
                 '*' which selects all files.
  --dry-run      If set, prevents new documents from being generated.
  --watch        If set, the command will keep running and watch for changes
                 in the package directory.
  --verbose      Enable verbose logging.
  --help         Show this message and exit.

quarto preview: Preview the site

Use quarto to preview the site:

quarto preview

Speeding up preview

Rewriting doc files

By default, the quartodoc build only re-writes doc pages when it detects a change to their content. This helps prevent quarto preview from trying to re-render every doc page–including those that haven’t changed.

Selectively building doc pages

Use the filter option with quartodoc build to generate a subset of doc pages. This is useful when you have a many (e.g. several hundred) doc pages, and want to test a change on a single page.

quartodoc build --filter 'get_object'

This option also accepts a wildcard pattern, which causes it to build docs for all matching objects.

# write the docs for the MdRenderer class, and any of its methods
# (e.g. MdRenderer.renderer)
quartodoc build --filter 'MdRenderer*'
Note

When using a name with a wildcard, be sure to put it in single quotes! Otherwise, your shell may try to “expand it” to match file names.