[source]

Source file discovery configuration

Guide: source.

source.dir
Type:
string
Default:
""

The directory the project’s own documents are discovered from, relative to this file (an absolute path, or one climbing out with .., is also accepted).

Unset or an empty string means the directory holding this configuration file. Setting it re-anchors every discovery glob — [source] include/exclude and each [parse.parsers.*] include — at each source root, so one pattern means the same thing under this directory and under every [[source.mounts]] root.

Supersedes the deprecated [project] srcdir: when both are set this one wins and srcdir is ignored.

source.exclude
Type:
array of strings

A list of glob patterns to exclude from the search.

This is the BASE list, and its default is the hygiene set (.git, node_modules, _build, dist, .venv, site-packages, …), so setting it REPLACES those defaults. Use extend_exclude to add to them.

With dir set, a pattern naming a path is matched under each source root; a pattern naming only a file name matches under every root either way.

source.extend_exclude
Type:
array of strings
Default:
[]

A list of glob patterns to extend the exclude list with.

Across an extend chain these ACCUMULATE: a child’s entries are added to the parent’s rather than replacing them, so a base configuration’s additions survive. exclude itself replaces.

source.extend_include
Type:
array of strings
Default:
[]

A list of glob patterns to extend the include list with.

Across an extend chain these ACCUMULATE: a child’s entries are added to the parent’s rather than replacing them, so a base configuration’s additions survive. include itself replaces.

Type:
boolean
Default:
false

If True, follow symbolic links when traversing source directories.

source.include
Type:
array of strings
Default:
["*.rst"]

A list of glob patterns to include in the search.

With dir set, a pattern naming a path is matched under each source root; a pattern naming only a file name matches under every root either way. Not read when parsers are declared under [parse.parsers.*] — they own file inclusion then.

source.mounts
Type:
array of tables
Default:
[]

Extra source trees folded into this project’s document set, each with its own docname prefix.

A child configuration’s mounts list replaces the parent’s entirely; entries are not merged.

Mounts apply to the project build. ubc check and ubc format discover files by walking for the nearest configuration file, and do not read mounts.

Each entry: An extra source tree, folded into the project’s document set.

Forms:

  • a table with dir: A directory whose tree is walked.

  • a table with files: An explicit list of files.

source.mounts[].attach_each
Type:
boolean
Default:
false

If true, attach every mounted document individually instead of just entry_doc, in files order.

For a files mount with an attach_to. On a dir mount, without attach_to, or beside a non-default entry_doc it is reported and ignored.

source.mounts[].attach_to
Type:
string
Default:
""

The host document whose table of contents gains an entry for this mount. Unset attaches nothing, leaving the mounted documents reachable only through references written by hand.

source.mounts[].entry_doc
Type:
string
Default:
""

The mount-relative document that attach_to points at. Unset or an empty string means "index".

source.mounts[].exclude
Type:
array of strings
Default:
[]

Glob patterns excluding files under the mount, relative to the mount root. The project’s own [source] exclude applies as well, so the hygiene defaults are not lost — and with [source] dir set its path-naming patterns are matched under THIS mount’s root too, so one written pattern excludes the same thing under every root.

A files mount has no walk to filter, so this is not read there.

source.mounts[].gitignore
Type:
boolean
Default:
true

If true, respect .gitignore files inside the mounted tree. Defaults to true, and is worth setting to false for a generated tree that a .gitignore deliberately hides — with true such a tree yields no documents at all. A files mount has no walk, so this is not read there.

source.mounts[].if
Type:
string

A condition deciding whether this mount is part of the build. Unset, the mount always is.

A Python-like expression over the variant data (var.edition == 'pro', 'net' in var.build.features), in the same grammar [[source.variant_sources]] uses for its own if: comparisons, in / not in, is None / is not None, .startswith(…) / .endswith(…), and / or / not, parentheses, nested var.* access, and the literals True / False. The condition must evaluate to a boolean, so a bare field (var.debug) is refused — write var.debug == False — and every field must be rooted at var.

The booleans are spelled True and False, not TOML’s true and false: this is an expression, not a TOML value, and a lower-case spelling is read as a field name and fails to evaluate.

A false condition gates the WHOLE mount off: it contributes no documents, nothing is wired into its attach_to host, and a toctree entry naming one of its documents reports the gating rather than a missing file. A condition that cannot be read, or cannot be evaluated against the variant data (an unknown var.* key included), gates the mount off as well and is reported — the safe direction for a key whose purpose is keeping content out of a build.

The whole mount is the unit, for both modes: this gates a files mount exactly as it gates a dir mount. Gating ONE file of a files mount is a different thing and is not supported, here or in [[source.variant_sources]].

source.mounts[].include
Type:
array of strings
Default:
[]

Glob patterns selecting which files under the mount are used, relative to the mount root.

Unset, the mount inherits the project’s [source] include. What that inherited list then means depends on which key names the project’s source root. Under [source] dir it is matched under THIS mount’s root, so it means here what it means at home. Under the deprecated [project] srcdir it stays anchored at the configuration folder, so an inherited pattern naming a path rather than only a file name matches nothing under a mount root outside the project and the mount yields no documents at all — give such a mount its own include.

Read only when no parsers are declared under [parse.parsers.*]; when they are, they own file inclusion for a mount as they do for the project’s own tree. A files mount has no walk to filter, so this is not read there either.

source.mounts[].mount_at
Type:
string
Default:
""

The docname prefix the mounted documents are given, e.g. "_generated/api". A relative docname: no leading /, no . or .. segment, no empty segment, no backslash, no leading or trailing whitespace; a trailing / is ignored.

Unset or an empty string mounts at the document root, where a mounted document can take the name of a host document.

source.mounts[].toctree_index
Type:
integer
Default:
0

Which of attach_to’s tables of contents receives the entry, counting from 0 in document order. Defaults to the first; a host document with no table of contents at all gains one. An index past the end of the ones it has is reported and nothing is wired.

source.mounts[].dir
Type:
string

The directory to mount, relative to the configuration file.

source.mounts[].files
Type:
array of strings

The files to mount, relative to the configuration file. Their directories are discarded: each file is named by its basename.

source.respect_gitignore
Type:
boolean
Default:
true

If True, respect .gitignore files.

source.variant_sources
Type:
array of tables
Default:
[]

Rules narrowing which files are part of the build, per build variant.

Each rule pairs a condition (if) with a set of globs (files). Every rule whose condition is false removes its files from the build; a file no false rule matches is unaffected. Rules only ever narrow, and their order does not matter.

The conditions are evaluated against the variant data ([variants] data merged over data_file, or the legacy [needs] keys), so switching variant data switches which files exist. A removed file is never read: it has no page, no toctree slot, and nothing it defines reaches search, cross-references or needs.json.

A child configuration’s variant_sources list replaces the parent’s entirely; entries are not merged.

Each entry: One [[source.variant_sources]] entry, as authored.

source.variant_sources[].files
Type:
array of strings

The files this rule gates, as glob patterns using the same pattern dialect and the same base as [source] exclude.

A pattern with no path separator matches by FILE NAME, so files = ["internal.rst"] gates every internal.rst in the project and in every mounted tree, not one file. Give a pattern a path (reference/internal.rst) to gate one place.

Two spellings that [source] exclude accepts are refused here, because they do not mean the same thing to every tool reading this file: {a,b} alternation, and a pattern climbing out of the project with ... Either one REFUSES the configuration: nothing is built until the pattern is rewritten. A rule this key cannot interpret the same way for every reader must not quietly leave its files in the build.

source.variant_sources[].if
Type:
string

The condition deciding whether this rule’s files are part of the build. A Python-like expression over the variant data (var.edition == 'pro', 'net' in var.build.features), which must evaluate to a boolean: a bare field (var.debug) is refused here, write var.debug == False instead, and so is a bare .upper() or .lower(), which yields a string. The predicates .startswith(…) and .endswith(…) yield a boolean and are valid on their own. Refusing the rest keeps one rule string meaning one thing to every tool that reads this file.

Supported: comparisons, in / not in, is None / is not None, .startswith(…) / .endswith(…), and / or / not, parentheses, nested var.* access, and the literals True / False. Anything else is a configuration error. A condition that cannot be evaluated — an unknown var.* key included — reports and EXCLUDES this rule’s files.

The booleans are spelled True and False, not TOML’s true and false: this is an expression, not a TOML value, and a lower-case spelling is read as a field name and fails to evaluate.