Bazel rules

The rules are loaded from @rinx//:defs.bzl:

load("@rinx//:defs.bzl", "rinx_doctest_tests", "rinx_inventory", "rinx_library", "rinx_site")

They work like cc_library and cc_binary. A rinx_library parses a set of documents, and a rinx_site assembles libraries into one HTML site. Each document is parsed and rendered by an action of its own, so Bazel rebuilds only what an edit affects.

rinx_library

Parses a set of reStructuredText documents. Its output is a parsed form of each document that a rinx_site renders, not HTML.

Attribute	Description
`srcs`	The `.rst` documents this library owns. Each becomes a page of the site, at its path relative to the package.
`deps`	Other `rinx_library` targets whose documents this library's toctrees include. Only toctrees need this: cross-references and links between documents are resolved across the whole site without it. A toctree naming a document that no library in `deps` provides fails the build.
`parse_data`	Files the documents read while they are parsed: the file behind a `.. csv-table:: :file:`, the sources `.. include::` and `.. literalinclude::` splice in, and the templates a Jinja `{% include %}` reads. A path resolves relative to the file the directive is written in, or to the source root with a leading `/`. An `.rst` file included this way must not also be in `srcs`, or it is published as a page of its own too.
`images`	The pictures `.. image::` and `.. figure::` show. They are copied into the site's `_images/` directory. An image a document shows but that is not declared here fails the site's build.
`diagrams`	Whether the documents may hold PlantUML diagrams (`.. uml::`, `.. plantuml::` and the entity diagrams). Off by default, so a library without diagrams pays nothing for them. A diagram in a library without it fails the build, naming this attribute. Keep diagram documents in a library of their own to keep the cost on them.
`entity_schema`	The project's entity schema, which declares directives such as `.. req::`; see Entities. Every library of a site and the site itself must name the same file.
`jinja`	Whether the `.rst` sources are rendered as Jinja templates before they are parsed, the transform a Sphinx project gets from a `source-read` hook. Off by default, since `{{` and `{%` are ordinary text in most documents. A document holding no Jinja delimiter is not rendered at all.
`jinja_context`	A dictionary of names a Jinja-rendered document may read, like Sphinx's `html_context`. A name that nothing binds is reported rather than rendered as the empty string.
`default_domain`	The domain unprefixed directives and roles such as `.. function::` belong to: `"py"` (the default) or `"c"`.

rinx_site

Assembles a site from rinx_library targets: it indexes every document the libraries bring in (transitively), renders one page per document, compiles the diagrams, and copies the images and the stylesheet. The output is the directory <name>_site_out. The site also writes an objects.inv, the inventory other Sphinx or rinx sites link into it through, available as the target's inventory output group.

Attribute	Description
`deps`	The `rinx_library` targets of the site.
`config`	A `rinx.toml` with the site's metadata; see The configuration file below. Defaults to one naming the project "Documentation".
`template`	The MiniJinja HTML template every page is rendered into. Defaults to the bundled one.
`css`	The stylesheet copied into the site. Defaults to the bundled one.
`entity_schema`	The same schema file the libraries name, if they name one.
`entity_templates`	Per-type HTML templates a schema's `template = "name.html"` refers to by basename. Omit it for the built-in rendering.
`inventories`	`rinx_inventory` targets: other sites this one links into. See Linking between documentation sites.
`strict_links`	If `True`, a broken cross-reference fails the build instead of only printing a warning. Off by default.

The configuration file

The site's config is a TOML file holding metadata only. It never contains paths: those are attributes of the rule, so that Bazel can move files around freely.

project = "My Project"
version = "1.2"
root_doc = "index"
highlight_language = "python"

[uml_configs]
monochrome = "skinparam monochrome true"

Key	Meaning
`project`	The name shown in the sidebar and in each page's title.
`version`	The version shown in the sidebar.
`root_doc`	The document every other one hangs off, without `.rst`. Defaults to `index`.
`highlight_language`	The language of code blocks that name none, like Sphinx's setting of the same name. A name that matches no language fails the build.
`collapse_entities`	Whether an entity's details are folded behind a disclosure. On by default.
`show_entity_updates`	Whether `.. entity-update::` renders a visible box of the changes it makes. On by default.
`uml_configs`	Named PlantUML preambles a diagram selects with `:config:`.

rinx_inventory

Declares another site's objects.inv that a rinx_site may link into, Sphinx's intersphinx. Nothing is downloaded while building: the file is vendored, pinned by an http_file with a sha256, or produced by another rinx_site. See Linking between documentation sites.

Attribute	Description
`src`	The `objects.inv` file. Required.
`base_url`	Where that site's pages are published: an absolute URL, or a path relative to the consuming site's root for a site deployed next to it. Required.
`inventory_name`	The name documents select this inventory by, as in :external+python:ref:`tut`. Defaults to the target's name.

rinx_doctest_tests

Runs the .. doctest:: and .. testcode:: blocks of one library's documents as a Bazel test, on the Python toolchain rinx brings along. Building a site never runs them; bazel test does. A test's result stays cached until the code in the blocks changes. Prose edits do not re-run it.

rinx_doctest_tests(
    name = "doctests",
    lib = ":docs",
)

Argument	Description
`name`	The name of the generated `py_test`.
`lib`	The `rinx_library` whose documents are tested. Its `deps` are not tested; each library carries its own doctest target.
`py_deps`	`py_library` targets the documented code imports.
`global_setup`, `global_cleanup`	A `.py` file run before or after every group, like Sphinx's `doctest_global_setup` and `doctest_global_cleanup`.
`size`, `tags`, …	Passed on to the generated `py_test`.

Every document of a library runs in one interpreter, and a change to one document's code re-runs the whole library's test. To narrow that, put the documents with doctests in a library of their own.