Module docs 

choir docs: the book, and the API documentation inside it.

Two renderers over one set of files. docs/*.md is the book’s source and is also pulled into the crates with #![doc = include_str!], so a page cannot say one thing in the book and another in cargo doc.

rustdoc is copied to book/api/ rather than left in the target directory. That is the whole reason this is one command instead of two: a book whose API links point outside the tree it was built into is a book whose API links 404 the moment it is copied anywhere.

Why this is not a shell script

It was one. The script computed the documentation directory as ${CARGO_TARGET_DIR:-target}/doc, which is right when the variable is exported, right when nothing sets it, and wrong when target-dir comes from a [build] table in a .cargo/config.toml, which cargo reads from every ancestor of the working directory. cargo doc then succeeded and the copy after it reported that cargo had produced nothing. target_dir_from_metadata asks cargo instead, and is tested against the shape cargo actually emits.

Structs

Built

What a successful build produced.

Enums

Failure

Why a build did not happen, phrased as the thing to do about it.

Constants

NODE_LINK_MARKER

The marker docs/README.md carries where a link to the node belongs.

Functions

api_index

The landing page rustdoc does not write.

build

Builds the book and the API documentation inside it.

find_root

The checkout from sits in, found by the file that defines the book.

open

Opens a built page in whatever the desktop uses, if anything does.

repoint_escaping_links

Repoints the links that leave the book.

stamp_node_link

Puts a link to the node into the page that carries NODE_LINK_MARKER.

target_dir_from_metadata

Cargo’s target directory, read out of cargo metadata output.