Project, source & scripts

This page covers the remaining ubproject.toml sections: project metadata, source file discovery, custom scripts, and the needs_json tree-view configuration.

project

Basic metadata about your documentation project.

[project]
name = "My Project"
version = "1.0.0"
description = "My project description"
srcdir = "src"

name

Type: string (optional)

The project name, displayed in various UI elements.

version

Type: string (optional)

The project version.

description

Type: string (optional)

A short description of the project.

srcdir

Type: string (optional, default: config directory)

A directory used for resolving paths in certain directives. Defaults to the directory containing the ubproject.toml file.

needs_json

Configuration for the Needs Index tree view in VS Code, which displays needs from a pre-built needs.json file.

[needs_json]
path = "relative/path/to/needs.json"
src = "."

path

Type: string (required)

Path to the needs.json file. Resolved relative to the directory containing ubproject.toml.

src

Type: string | null (default: null)

Path to the source directory, used to resolve docname values to file paths for click-to-source navigation. When null, source locations are not resolved.

source

The [source] section determines which files ubCode processes. Use it to include additional file types, exclude build artifacts, or control how the file walker traverses your project.

Minimal example

[source]
respect_gitignore = true
extend_exclude = ["temp/**", "*.tmp"]

Core options

respect_gitignore

Type: boolean (default: true)

When enabled, automatically excludes files that are ignored by:

• .gitignore files

• .git/info/exclude

• Global gitignore configuration

• .ignore files (used by tools like ripgrep)

follow_links

Type: boolean (default: false)

When enabled, symbolic links will be followed when traversing source directories. This allows you to include files or directories that are symlinked from other locations in your filesystem.

Warning

Enabling this option may lead to infinite recursion if there are circular symbolic links. Use with caution and ensure your directory structure does not contain symlink loops.

[source]
follow_links = true

include

Type: array (default: ["*.rst"])

Base list of glob patterns for files to include. By default, only reStructuredText files are processed.

exclude

Type: array (default: comprehensive list)

Base list of glob patterns for files and directories to exclude. The default list includes common directories that typically don’t contain source documentation:

exclude = [
    ".bzr", ".direnv", ".eggs", ".git", ".git-rewrite",
    ".hg", ".svn", ".venv", ".vscode", "_build", "build",
    "dist", "node_modules", "site-packages"
]

extend_exclude

Type: array (default: [])

Additional patterns to add to the exclude list without replacing the defaults.

extend_include

Type: array (default: [])

Additional patterns to add to the include list without replacing the defaults.

Glob pattern types

Single-path patterns

Match anywhere in the directory tree:

• directory — matches any directory named “directory”

• foo.rst — matches any file named “foo.rst”

• foo_*.rst — matches files like “foo_test.rst”, “foo_doc.rst”

Relative patterns

Match specific paths relative to the project root:

• ./foo.rst — matches “foo.rst” in project root only

• directory/foo.rst — matches “foo.rst” in “directory” only

• directory/*.rst — matches all RST files in “directory”

• docs/**/*.rst — matches RST files anywhere under “docs”

Pattern precedence

Exclude patterns take precedence over include patterns. If a file matches both an include and exclude pattern, it will be excluded.

Tip

To see which patterns are active: ubc config

To see all discovered files: ubc build list-documents

Common configurations

Multi-format documentation:

[source]
extend_include = ["*.md", "*.txt"]
extend_exclude = ["README.md", "CHANGELOG.md"]

Excluding build artifacts:

[source]
extend_exclude = [
    "build/**",
    "_build/**",
    "*.tmp",
    "temp/**"
]

Including only specific directories:

[source]
include = ["docs/**/*.rst", "specifications/**/*.rst"]
exclude = ["**"]  # Exclude everything else

See also

For detailed glob syntax documentation, see the globset documentation.

scripts

Register custom scripts to run from VS Code or the command line. In VS Code they can be accessed via the command palette (Ctrl+Shift+P) by selecting “ubCode: Run Script in Terminal”.

Each key is a script, and each value is the configuration for that script. Normally the value is an object with different keys — the most important being cmd which holds the command to execute. If only cmd is set, the object notation is optional:

[scripts]
sphinx1 = "sphinx-build -b html . _build/html {{filepath}}"
sphinx2 = { cmd = "sphinx-build -b html . _build/html {{filepath}}", env = { SPHINXOPTS = "-W" }, terminal = "name", jinja = true }

Additionally, the chain key can be used in place of cmd to run multiple commands in sequence:

[scripts]
rm_build = "rm -rf _build"
sphinx = "sphinx-build -b html . _build/html {{filepath}}"
"sphinx:clean" = { chain = ["rm_build", "sphinx"] }

The following keys are possible for a script:

• cmd: The command to execute.

• chain: A list of scripts to execute in sequence.

• env: A map of environment variables to set.

• terminal: What to name the terminal in VS Code. If not set, the terminal will be named after the script key. Terminal names are unique, so if a terminal with the same name already exists, it will be reused.

• jinja: If True (the default), the command is treated as a jinja template, which can take the following variables:

  • {{ confdir }}: The directory containing the configuration file.

  • {{ filepath }}: The currently active file in VS Code

The current working directory for the script is set as the directory containing the configuration file.