You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The idea is to be able to write intra-doc-like links that point to external resources, e.g.:
/// Uses the kernel's C [`struct mutex`].
where the URL is automatically provided, e.g. to some C documentation. Similarly, it could be use to avoid duplicating URLs that need to be manually updated, e.g. like a BibTeX database file. For instance, references to external articles, page/webs, papers, Wikipedia entries, etc.
To define those links, rustdoc could be given a "external references" file containing a map of (term, URL) pairs (e.g. in a JSON or Markdown-references-like file with one reference per line), possibly passed via the CLI, e.g.:
--external-references-file books.json
That way, the user is the one that defines the links and terms, possibly exporting them from other tooling (such as a documentation tool for another programming language).
Multiple files could also be allowed -- having different files for different topics/categories of references may be useful/cleaner for users.
An interesting extension could be to allow references to contain extra metadata (i.e. not just the URL), like in BibTeX. rustdoc could then potentially render that metadata somehow, like Wikipedia's references (e.g. when clicking them, or when clicking a small information button close to the link, or as a footnote, or on hover...). Another possibility is that, even without any extra metadata, rustdoc could also decide to render them differently than "normal links".
There is potential for ambiguity with existing links. Possibly a syntax could be provided to disambiguate (whether required in all cases or just in cases of ambiguity), as suggested by @aDotInTheVoid, e.g.:
/// Uses the kernel's [extern@`struct mutex`].
Currently (Rust 1.78), when one uses an intra-doc link that matches a Markdown one (i.e. the intra-doc link title is the same as the Markdown link label of a link reference definition), rustdoc renders it as the Markdown link, rather than the intra-doc link, without warning, e.g.:
/// This ambiguous link ([`ThisModule`]) goes to the website, not to the Rust item.////// [`ThisModule`]: https://rust-for-linux.com
An alternative could have been to use:
--markdown-after-content references.md
with a references.md file with:
[Wikipedia]: https://www.wikipedia.org
but currently (Rust 1.78) those references cannot be used from elsewhere. Instead, a potential --markdown-after-every-item could work.
Similarly, including the references via include_str! as suggested by @jyn514 works, e.g.:
/// Here are all the docs, with [Wikipedia] links.///#[doc = include_str!("references.md")]
but requires doing so in each case/item (rather than globally).
Status: Idea seemed reasonable to maintainers, RFC to be written.
The kernel has a lot of configuration options and it would be useful to have a way to generate the docs independently of the particular kernel configuration.
A partial workaround is having an allyesconfig configuration (or similar) generated for each architecture.
It turns out the new behavior is intended, and the fact that the links still got generated was just a compatibility measure for docs.rs, which will go away in Rust 1.71.
ICE: rustdoc's --test option may call rustc with too many arguments.
Features that we would like to see
Required (we almost certainly want them)
External references map file.
The idea is to be able to write intra-doc-like links that point to external resources, e.g.:
/// Uses the kernel's C [`struct mutex`].
where the URL is automatically provided, e.g. to some C documentation. Similarly, it could be use to avoid duplicating URLs that need to be manually updated, e.g. like a BibTeX database file. For instance, references to external articles, page/webs, papers, Wikipedia entries, etc.
To define those links,
rustdoc
could be given a "external references" file containing a map of (term, URL) pairs (e.g. in a JSON or Markdown-references-like file with one reference per line), possibly passed via the CLI, e.g.:That way, the user is the one that defines the links and terms, possibly exporting them from other tooling (such as a documentation tool for another programming language).
Multiple files could also be allowed -- having different files for different topics/categories of references may be useful/cleaner for users.
An interesting extension could be to allow references to contain extra metadata (i.e. not just the URL), like in BibTeX.
rustdoc
could then potentially render that metadata somehow, like Wikipedia's references (e.g. when clicking them, or when clicking a small information button close to the link, or as a footnote, or on hover...). Another possibility is that, even without any extra metadata,rustdoc
could also decide to render them differently than "normal links".There is potential for ambiguity with existing links. Possibly a syntax could be provided to disambiguate (whether required in all cases or just in cases of ambiguity), as suggested by @aDotInTheVoid, e.g.:
/// Uses the kernel's [extern@`struct mutex`].
Currently (Rust 1.78), when one uses an intra-doc link that matches a Markdown one (i.e. the intra-doc link title is the same as the Markdown link label of a link reference definition),
rustdoc
renders it as the Markdown link, rather than the intra-doc link, without warning, e.g.:An alternative could have been to use:
with a
references.md
file with:but currently (Rust 1.78) those references cannot be used from elsewhere. Instead, a potential
--markdown-after-every-item
could work.Similarly, including the references via
include_str!
as suggested by @jyn514 works, e.g.:but requires doing so in each case/item (rather than globally).
Status: Idea seemed reasonable to maintainers, RFC to be written.
Cc: @aDotInTheVoid, @GuillaumeGomez, @jyn514.
rustdoc
lint to flag potential intra-doc links.rustdoc
lint to flag potential intra-doc links rust-lang/rust#131510.Documentation under conditional compilation.
allyesconfig
configuration (or similar) generated for each architecture.Custom logo/favicon flag (for local/bundled image files).
Nice to have (not critical, we could workaround if needed, etc.)
Collapsed-by-default (or switch) for uncommon/advanced APIs.
alloc
if fallible allocations were to be added (try_*
).Switch for private/hidden items documentation.
--document-private-items
and--document-hidden-items
, but at runtime.doc_cfg
,auto_doc_cfg
,cfg_hide
.External
doc(cfg(...))
map file (customization in general of the rendered banner).doc(cfg(...))
rust-lang/rust#87139.Add copy button for code blocks.
Low priority (we will likely not use them in the end)
Done (stabilized, fixed, not needed anymore, etc.)
Jump to definition (i.e. links in source view,
--generate-link-to-definition
).rustdoc @argfile
.Bugs that we would like to see fixed
Required (we almost certainly want them)
Nice to have (probably not critical, we could workaround if needed, etc.)
super
in doctests errors.super
in doctests errors rust-lang/rust#130274.Low priority (we will likely not use them in the end)
Done (stabilized, fixed, or not needed anymore, etc.)
Avoid requiring an absolute path for the target spec file.
broken_intra_doc_links
behavior change withmacro_rules
not in scope since 1.63.rustdoc::broken_intra_doc_links
behavior change withmacro_rules
not in scope since 1.63 rust-lang/rust#106142.ICE:
rustdoc
's--test
option may callrustc
with too many arguments.rustdoc
's--test
option may callrustc
with too many arguments rust-lang/rust#122722.rustdoc --test
: Prevent reaching the maximum size of command-line by using files for arguments if there are too many rust-lang/rust#122840 (1.79).The text was updated successfully, but these errors were encountered: