Open ojeda opened 3 years ago
lolbinarycat
commented
3 weeks ago Idea seemed reasonable to maintainers, RFC to be written.
Any progress on that? I've been working on rustdoc, and recently I've been cleaning up a few things in the intra-doc link system.
ojeda
commented
2 weeks ago Not yet -- I will eventually get to it, since we are definitely interested in it. I have had a few more ideas around it. If you have time to put into it, please let me now!
lolbinarycat
commented
2 weeks ago I have plenty of time, the limitation is actually if t-rustdoc has enough time to review the contributions!
being able to say "rust4linux wants it" would probably help a fair bit towards getting it prioritized, though.
ojeda
commented
2 weeks ago That makes sense, yeah.
If you have a lot of time, and want to work on the feature, then please go ahead (and thanks a lot!), it will be a while until I can put time into that due to other priorities. I am happy to help or co-author or something like that. If what you want is write code rather than the RFC, then I think for a feature like that having a prototype implementation could also help.
Please feel free to contact me by email or in the Rust or Rust for Linux Zulips.
Note: there is the "A-rust-for-linux" label in the
rustrepository: https://github.com/rust-lang/rust/labels/A-rust-for-linux.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.:
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,
rustdoccould 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.
rustdoccould 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,rustdoccould 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.:
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),
rustdocrenders 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.mdfile with:but currently (Rust 1.78) those references cannot be used from elsewhere. Instead, a potential
--markdown-after-every-itemcould 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.
[ ]
rustdoclint to flag potential intra-doc links.[ ] Documentation under conditional compilation.
allyesconfigconfiguration (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.
allocif fallible allocations were to be added (try_*).[ ] Switch for private/hidden items documentation.
--document-private-itemsand--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).[ ] Add copy button for code blocks.
Low priority (we will likely not use them in the end)
Done (stabilized, fixed, not needed anymore, etc.)
[x] Jump to definition (i.e. links in source view,
--generate-link-to-definition).[x]
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.)
superin doctests errors.Low priority (we will likely not use them in the end)
Done (stabilized, fixed, or not needed anymore, etc.)
[x] Avoid requiring an absolute path for the target spec file.
[x]
broken_intra_doc_linksbehavior change withmacro_rulesnot in scope since 1.63.[x] ICE:
rustdoc's--testoption may callrustcwith too many arguments.