Multiple Builds¶
When creating documentation, it can be desireable to produce multiple copies of the documentation, where each copy is intended for a different audience. For example, “public” docs and “internal” docs.
By default, the build system will produce “public” docs. Extra builds can be specified by adding entries under the
[repo_docs.projects.*.builds.*] table header in repo.toml. The relevant section of repo.toml follows:
# this defines the "public" build
[repo_docs.projects.project-with-extra-builds]
docs_root = "examples/project-with-extra-builds"
name = "Example: Project with Extra Builds"
# we don't want "internal-only.rst" in the public build
sphinx_exclude_patterns = [
"internal-only.rst",
"tools"
]
# we want to link back to repo_docs from this build so we add it as a dependency
deps = [
[ "repo_docs", "_build/docs/repo_docs/latest" ],
]
# this defines the "internal" build
[repo_docs.projects.project-with-extra-builds.builds.internal]
# settings are inherited from the "public" build, but can be redefined as we
# do with 'name' here:
name = "Example: Project with Extra Builds (Internal)"
# reset the exclude patterns so that "internal-only.rst" isn't excluded
sphinx_exclude_patterns = [
"tools"
]
The snippet above defines two builds:
The “public” build. The build is implicitly defined under
[repo_docs.projects.project-with-extra-builds]as it is the default build.The “internal” build. This is specified under
[repo_docs.projects.project-with-extra-builds.builds.internal].
Builds inherit (and can override) settings from the “public” build. Above, the “public” build’s name is redefined
by the “internal” build while docs_root is inherited since it is not redefined.
Conditionally Including an Entire Document Based on the Build¶
By default, the documentation system will include any .rst file that is found in the project’s docs_root defined
in repo.toml. Thus, to limit which docs are included in a build, repo.toml’s sphinx_exclude_patterns can be
used. See the repo.toml snippet above for an example.
Note
In practice, files conditionally included should have :orphan: at the top of the file since they cannot be
conditionally included in a .. toctree:: directive. This is a limitation to the .. toctree:: directive.
Conditionally Including Parts of a Document Based on the Build¶
The .. ifconfig:: directive can be used to conditionally include parts of a document. For example:
.. ifconfig:: build_name in ('internal')
This text will only appear in the "internal" build of the documentation. It can contain links to other
docs: :ref:`internal_only_file`.
The .. ifconfig:: mechanism has limitations. For example, you’re unable to use .. ifconfig:: within ..
toctree::.
See Example: Project with Extra Builds for an example.
Controlling the Build to Build¶
By default, all builds found in repo.toml are built. The user can be selective as to the build to build with the
--build flag:
repo docs --build internal