Module api_links 

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

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, D38).

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

D38: 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.

This generator was once recorded as needing 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. That leaves the full twelve-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.

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 is defined in the private atune_core::storage::conformance::macros module and its only path is atune_core::storage_conformance_tests. 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.

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 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 — and a generator never invents structure the code does not have. Python members are carried, because mkdocstrings mints one anchor per member and the site build validates it.

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.

Re-exports

pub use api_map::ApiMap;

pub use api_map::map;

pub use links::Links as ApiLinks;

Modules

api_map 🔒

The API-link map assembled from its source registries.

cli 🔒

The CLI half: every command in clap’s tree, pointed at its toc slug.

error 🔒

Error construction shared by API-link registry readers.

links 🔒

The generated API-link document.

python 🔒

The Python half: the live module’s symbols, each pointed at its mkdocstrings anchor or its submodule’s section.

registry 🔒

Workspace crate classification used by the API link map.

rust 🔒

The Rust half: the facade’s re-export lists, each name followed to its declaration for the rustdoc page it lives on.

yaml 🔒

YAML rendering for the generated API link map.