Module api_links 

api-links — docs/api_links.yml, the checked API-link map of §3 point 3.

What the map is for

Prose never spells a reference URL. A page names a symbol — atune::Study, atune.create_study, atune run — and code_header in docs/_build/macros.py resolves it through this file. Polars logs a warning for a key it cannot find; atune generates the map from the current API instead, so cargo dev generate-all --mode check fails on an identifier the API no longer carries (D29, docs/design/11-documentation-plan.md §3 point 3, §7).

The one rule that decides a Rust link, encoded rather than answered

§12: a symbol from a published crate, on a released site version, links to docs.rs/<crate>/<version>/…, which is where a Rust reader goes by reflex; everything else — the dev version, and any symbol from a publish = false crate — links to that version’s /api/rust/, which is built for every site version precisely so the unpublished crates have a reference at all.

Nothing is released yet, so today every Rust symbol resolves to the self-hosted form. That is an answer, and the answer is not what this generator writes. It writes the two URL templates and the two crate lists — read from each manifest’s own publish key — and the resolver applies them against the version being built. Publishing atune 0.1 therefore changes no byte of this file and no line of any page: it changes which branch the resolver takes.

Three registries, no wheel

• Rust: the facade’s own re-export lists in crates/atune/src/lib.rs, the same registry the catalog generator reads (D33). A name is followed to its declaration to learn its kind, because rustdoc’s file name is struct.Foo.html / trait.Foo.html / fn.foo.html / foo/index.html, and a kind this generator cannot determine is an error rather than a guess.
• Python: the live module, through the embedded interpreter atune_python::init_python the pystub generator already starts. No wheel — see the note below.
• CLI: atune_cli::Cli::command(), the same clap tree the cli generator walks, so a command appears in the map because clap knows about it.

§7’s Needs column says this generator needs a built wheel, which is why it alone was to wait for docs.yml. Measured: it does not. The Python half of the map is the module’s __all__ and its classes’ members, which append_to_inittab! + Python::initialize() deliver in-process exactly as they do for pystub (§1.3.47). That is the third wrong entry in that column (§1.3.37 found the other two), and it leaves the full eleven-generator registry checkable in the fast per-push gate.

Where a Rust re-export’s page actually lives

Measured against cargo doc --workspace --all-features --no-deps, because guessing a URL shape is how a link map starts lying:

Re-export	Page
pub use atune_core::sampler::Random; in pub mod sampler	atune/sampler/struct.Random.html
pub use crate::gp::GpEi; in pub mod sampler	atune/gp/struct.GpEi.html, not atune/sampler/…
pub use open_storage::open_storage; (private mod)	atune/fn.open_storage.html
pub use auto_sampler::auto_sampler; (pub mod)	atune/auto_sampler/fn.auto_sampler.html

The rule behind all four: rustdoc inlines a re-export whose original path is not publicly reachable — every cross-crate one, and a same-crate one out of a private module — and merely links one whose original is public, leaving the page at the declaration site. So a same-crate re-export out of a pub mod resolves to the source module, and everything else resolves to the re-exporting module.

“Publicly reachable” is transitive and is computed rather than assumed: Sources::public_scopes holds every module scope with a pub chain all the way to its crate root. Testing only a path’s first segment was enough while the walk stopped at the crate root and wrong the moment it did not (§1.3.100).

Two further rules the walk depends on, both measured the same way:

• A macro is documented at its crate’s root, however deep the file it is written in. #[macro_export] macro_rules! storage_conformance_tests lives in atune_core::storage::conformance and its only path is atune_core::storage_conformance_tests (§1.3.113). Same for every proc macro.
• A crate’s tree is named after its lib target, not its package. atune_py is [lib] name = "atune", so cargo doc writes it into the facade’s directory and it has no tree of its own (§1.3.114).

What the map carries, and what it deliberately does not

It carries every module the facade exports and that module’s members, at whatever depth: atune::storage::conformance::run_all, atune::space::dsl::parse, atune::pb2::gp::TvGp. It also carries one key per crate whose rustdoc tree is its own, so a page can link a crate’s reference as a whole. cargo dev check-api-links (G14) checks both directions of that against a built tree.

Rust members of an item. atune::Study is in the map; Study::optimize is not. rustdoc’s member anchors differ by kind (#method.x, #tymethod.x, #associatedconstant.X) and none of them is derivable from a re-export list, so a member key would be a guessed anchor — exactly the invention §7 constraint 3 forbids. Python members are carried, because mkdocstrings mints one anchor per member and the site build validates it.

The prelude’s members. atune::prelude::Study is atune::Study by construction — the catalog generator fails if the two lists ever disagree — and atune::prelude::Arc is std’s. The module itself is in the map; its names are reached under their crate-root keys.

Anything under a private module. atune::gp::kernel does not resolve, so atune/gp/kernel/struct.Matern52.html — which rustdoc writes anyway — is a page no path names; the one a reader reaches is the inlined atune/gp/struct.Matern52.html, which the map does carry (§1.3.115).

Structs

ApiLinks

Generates the API-link map.

ApiMap

The map’s contents, before they are rendered.

Leaf 🔒

One re-exported leaf: the public name and the source it was re-exported from.

Pending 🔒

A module whose members have not been mapped yet.

Reexport 🔒

One source re-export, retained so a later re-export can be followed.

Sources 🔒

The workspace’s own sources, indexed for kind resolution.

Walk 🔒

The Rust walk’s running state.

Enums

Kind 🔒

What rustdoc calls an item, which is what its file is named after.

Constants

CLI_PAGE 🔒

The mkdocs page carrying the CLI reference.

CORE 🔒

The model crate the facade re-exports from.

CRATES_DIR 🔒

The workspace’s crate directory, one manifest per subdirectory.

DERIVE 🔒

The derive crate, whose one proc macro the facade re-exports.

FACADE 🔒

The facade, whose re-export lists are the Rust half of the map (D33).

FACADE_CRATE 🔒

The facade’s name, and the first path segment of every symbol it exports.

FACADE_LIB 🔒

The facade’s crate root, which holds every re-export list.

GENERATOR 🔒

This generator’s name, for fail-closed error messages.

MAX_HOPS 🔒

How many re-exports of a re-export this generator will follow.

PRELUDE 🔒

The module whose members are the crate root’s own (see the module docs).

PYTHON_PAGE 🔒

The mkdocs page carrying the Python reference.

SUBMODULE_SECTIONS 🔒

The two Python submodules that have no mkdocstrings anchors of their own, and the section heading each one’s symbols are pointed at instead.

SYNTHETIC_SUBCOMMAND 🔒

The clap-synthesised subcommand, which is not part of atune’s surface.

Functions

check_crates_cover_rust 🔒

Fails if a Rust symbol’s page sits in a crate the map does not classify.

check_submodules_use_their_section 🔒

Fails if a submodule symbol was given a mkdocstrings anchor.

cli_symbols 🔒

Every documented command, as its spelling → page.md#anchor.

collect_commands 🔒

Records one command and recurses into its subcommands.

collect_leaves 🔒

Flattens one pub use into its leaf names, keeping the path each came from.

crate_root_of 🔒

The src directory of the crate a file belongs to.

crates_with_own_tree 🔒

Every crate whose rustdoc tree is its own, and therefore has a root page.

disambiguate 🔒

Flattens a multimap into the map the file carries.

doc_dir_of 🔒

The doc directory a source scope’s pages sit in.

expansion_kind 🔒

The one kind a macro_rules! expansion declares at its top level, if exactly one.

has_attribute 🔒

Does this item carry #[<name>]?

has_doc_attribute 🔒

in_scope 🔒

Whether a source file lies inside a module scope.

insert 🔒

Records one symbol’s page under its key.

is_doc_hidden 🔒

is_doc_hidden_item 🔒

is_doc_inline 🔒

is_public 🔒

Is this visibility a bare pub?

item_kinds 🔒

The public names one item declares, with their kinds.

join 🔒

A rustdoc page path, under a module directory or at a tree’s own root.

macro_declared 🔒

Public items declared by a macro_rules! expansion, which no parse of the source can see as items: the struct is in the expansion, not in the file.

manifest_of 🔒

The manifest that declares a package of this name.

map

Reads the three registries and the crate classification.

module_dir_of 🔒

The directory a file’s own submodules live in.

module_file 🔒

The source file a module scope’s items are written in.

proc_macro_kind 🔒

The macro a #[proc_macro*] function declares, and its kind.

public_module_names 🔒

The scopes of the pub mod declarations reachable from one module body.

public_scopes 🔒

Every module source scope a public path reaches, per indexed crate.

python_symbols 🔒

Every Python symbol, as its dotted path → page.md#anchor.

render_crate_list 🔒

One published_crates: / unpublished_crates: list.

render_section 🔒

One symbol section, with the sentence saying where it came from.

render_yaml 🔒

The banner, the policy block — the rule as data — and the three sections.

resolve_aliases 🔒

Repoints every alias at the anchor its canonical target resolved to.

rust_symbols 🔒

Every Rust symbol the guide may name, as atune::… → rustdoc path.

scalar 🔒

One YAML scalar’s value, read from the text after its key.

site_base 🔒

mkdocs.yml’s site_url, with a guaranteed trailing slash.

top_level_public_kinds 🔒

The kinds of the pub <keyword> declarations at the top level of a token stream.

unclassifiable 🔒

Wraps a message as this generator’s fail-closed error.

walk_use_tree 🔒

Walks a use tree, accumulating the module path as it descends.

workspace_crates 🔒

Every workspace crate, and whether it is published to crates.io.