//sphinxdocs:sphinx.bzl

Rules to generate Sphinx documentation.

The general usage of the Sphinx rules requires two pieces:

Using sphinx_docs to define the docs to build and options for building.
Defining a sphinx-build binary to run Sphinx with the necessary dependencies to be used by (1); the sphinx_build_binary rule helps with this.

Defining your own sphinx-build binary is necessary because Sphinx uses a plugin model to support extensibility.

The Sphinx integration is still experimental.

sphinx_build_binary(name, py_binary_rule='<function py_binary from //python:py_binary.bzl>', **kwargs)

Create an executable with the sphinx-build command line interface.

The deps must contain the sphinx library and any other extensions Sphinx needs at runtime.

Args:

name – (str)
name of the target. The name “sphinx-build” is the conventional name to match what Sphinx itself uses.
py_binary_rule – (callable) (default ‘<function py_binary from //python:py_binary.bzl>’)
A py_binary compatible callable for creating the target. If not set, the regular py_binary rule is used. This allows using the version-aware rules, or other alternative implementations.
kwargs – (dict)
Additional kwargs to pass onto py_binary. The srcs and main attributes must not be specified.

sphinx_docs(*, name, srcs=[], deps=[], renamed_srcs={}, sphinx, config, formats, strip_prefix='', extra_opts=[], tools=[], allow_persistent_workers=True, **kwargs)

Generate docs using Sphinx.

Generates targets:

<name>: The output of this target is a directory for each format Sphinx creates. This target also has a separate output group for each format. e.g. --output_group=html will only build the “html” format files.
<name>.serve: A binary that locally serves the HTML output. This allows previewing docs during development.
<name>.run: A binary that directly runs the underlying Sphinx command to build the docs. This is a debugging aid.

Args:

name – (Name)
name of the docs rule.
srcs – (list[label]) (default [])
The source files for Sphinx to process.
deps – (list[label]) (default [])
of sphinx_docs_library targets.
renamed_srcs – (dict[label, dict]) (default {})
Doc source files for Sphinx that are renamed. This is typically used for files elsewhere, such as top level files in the repo.
sphinx – (label)
the Sphinx tool to use for building documentation. Because Sphinx supports various plugins, you must construct your own binary with the necessary dependencies. The sphinx_build_binary rule can be used to define such a binary, but any executable supporting the sphinx-build command line interface can be used (typically some py_binary program).
config – (label)
the Sphinx config file (conf.py) to use.
formats – (list of str) the formats (-b flag) to generate documentation in. Each format will become an output group.
strip_prefix – (str) (default “”)
A prefix to remove from the file paths of the source files. e.g., given //docs:foo.md, stripping docs/ makes Sphinx see foo.md in its generated source directory. If not specified, then native.package_name is used.
extra_opts – (list[str]) (default [])
Additional options to pass onto Sphinx building. On each provided option, a location expansion is performed. See - -.
tools – (list[label]) (default [])
Additional tools that are used by Sphinx and its plugins. This just makes the tools available during Sphinx execution. To locate them, use extra_opts and $(location).
allow_persistent_workers – (bool) (default True)
(experimental) If true, allow using persistent workers for running Sphinx, if Bazel decides to do so. This can improve incremental building of docs.
kwargs – (dict)
Common attributes to pass onto rules.

sphinx_inventory(name, src, **kwargs)

Creates a compressed inventory file from an uncompressed on.

The Sphinx inventory format isn’t formally documented, but is understood to be:

# Sphinx inventory version 2
# Project: <project name>
# Version: <version string>
# The remainder of this file is compressed using zlib
name domain:role 1 relative-url display name

Where:

<project name> is a string. e.g. Rules Python
<version string> is a string e.g. 1.5.3

And there are one or more name domain:role ... lines

name: the name of the symbol. It can contain special characters, but not spaces.
domain:role: The domain is usually a language, e.g. py or bzl. The role is usually the type of object, e.g. class or func. There is no canonical meaning to the values, they are usually domain-specific.
1 is a number. It affects search priority.
relative-url is a URL path relative to the base url in the confg.py intersphinx config.
display name is a string. It can contain spaces, or simply be the value - to indicate it is the same as name