Guillaume Gomez
5864247b10
Give more information into extracted doctest information
2025-06-10 13:54:46 +02:00
Guillaume Gomez
2c8a9cccd9
Rollup merge of #140560 - Urgau:test_attr-module-level, r=GuillaumeGomez
...
Allow `#![doc(test(attr(..)))]` everywhere
This PR adds the ability to specify [`#![doc(test(attr(..)))]`](https://doc.rust-lang.org/nightly/rustdoc/write-documentation/the-doc-attribute.html#testattr ) ~~at module level~~ everywhere in addition to allowing it at crate-root.
This is motivated by a recent PR #140323 (by ````@tgross35)```` where we have to duplicate 2 attributes to every single `f16` and `f128` doctests, by allowing `#![doc(test(attr(..)))]` at module level (and everywhere else) we can omit them entirely and just have (in both module):
```rust
#![doc(test(attr(feature(cfg_target_has_reliable_f16_f128))))]
#![doc(test(attr(expect(internal_features))))]
```
Those new attributes are appended to the one found at crate-root or at a previous module. Those "global" attributes are compatible with merged doctests (they already were before).
Given the small addition that this is, I'm proposing to insta-stabilize it, but I can feature-gate it if preferred.
Best reviewed commit by commit.
r? ````@GuillaumeGomez````
2025-06-07 22:22:55 +02:00
bors
e6152cdf5b
Auto merge of #141573 - nnethercote:rustdoc-alloc-cleanups, r=camelid
...
rustdoc: cleanups relating to allocations
These commits generally clean up the code a bit and also reduce allocation rates a bit.
r? `@camelid`
2025-05-30 08:55:18 +00:00
Nicholas Nethercote
4f1f1a2b57
Avoid some unnecessary cloning.
2025-05-26 16:47:44 +10:00
binarycat
4ef35bcaef
rustdoc: use descriptive tooltip if doctest is conditionally ignored
...
fixes https://github.com/rust-lang/rust/issues/141092
2025-05-24 14:15:20 -05:00
Urgau
9d9705f4c3
Collect and use #![doc(test(attr(..)))] at module level too
2025-05-22 20:10:32 +02:00
Guillaume Gomez
f4d41a5cbd
Create a builder for DocTestBuilder type
2025-05-02 13:57:53 +02:00
Guillaume Gomez
b791eaa448
Emit a warning if the doctest main function will not be run
2025-05-02 13:57:53 +02:00
Matthias Krüger
610ed826e3
Rollup merge of #137096 - ehuss:stabilize-doctest-xcompile, r=fmease
...
Stabilize flags for doctest cross compilation
This makes the following changes in preparation for supporting doctest cross-compiling in cargo:
- Renames `--runtool` and `--runtool-arg` to `--test-runtool` and `--test-runtool-arg` to maintain consistency with other `--test-*` arguments.
- Stabilizes the `--test-runtool` and `--test-runtool-arg`. These are needed in order to support cargo's `target.runner` option which specifies a runner to execute a cross-compiled doctest (for example, qemu).
- Stabilizes the `--enable-per-target-ignores` flag by removing it and making it unconditionally enabled. This makes it possible to disable a doctest on a per-target basis, which I think will be helpful for rolling out this feature.
These changes were suggested in https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/stabilizing.20doctest.20xcompile/near/409281127
The intent is to stabilize the doctest-xcompile feature in cargo. This will help ensure that for projects that do cross-compile testing that their doctests are also covered. Currently there is a somewhat surprising behavior that they are ignored.
Closes https://github.com/rust-lang/rust/issues/64245
try-job: x86_64-msvc-1
2025-04-25 00:53:58 +02:00
Noah Lev
8b227a42fa
rustdoc: Enable Markdown extensions when looking for doctests
...
We should enable these to avoid misinterpreting uses of the extended
syntax as code blocks. This happens in practice with multi-paragraph
footnotes, as discovered in #139064 .
2025-04-09 13:04:57 -04:00
Matthias Krüger
bdc5adfe78
Rollup merge of #138678 - durin42:rmeta-stability, r=fmease
...
rustc_resolve: fix instability in lib.rmeta contents
rust-lang/rust@23032f31c9 accidentally introduced some nondeterminism in the ordering of lib.rmeta files, which we caught in our bazel-based builds only recently due to being further behind than normal. In my testing, this fixes the issue.
2025-03-28 12:59:55 +01:00
Eric Huss
7251b466a4
Remove and stabilize --enable-per-target-ignores
...
This removes the `--enable-per-target-ignores` and enables it
unconditionally.
2025-03-27 19:06:48 -07:00
Augie Fackler
77eb97d9a9
librustdoc: also stabilize iteration order here
2025-03-27 11:59:04 -04:00
Takayuki Maeda
90c541d637
ignore doctests only in specified targets
...
add necessary lines
fix ui test error
2025-03-25 15:39:41 +09:00
Matthias Krüger
e8326805c7
Rollup merge of #138535 - yotamofek:pr/rustdoc/lang-string-parse-cleanup, r=notriddle
...
Cleanup `LangString::parse`
Flatten some `if`s into match patterns
Use `str::strip_prefix` instead of `starts_with`+indexing
Avoid redundant tests for `extra.is_some()`
2025-03-22 11:59:17 +01:00
Michael Goulet
380ce74401
Suppress must_use in compiler and tools
2025-03-16 17:47:57 +00:00
Yotam Ofek
eca391fbd4
Cleanup LangString::parse
...
Flatten some `if`s into match patterns
Use `str::strip_prefix` instead of `starts_with`+indexing
Avoid redundant tests for `extra.is_some()`
2025-03-15 13:10:47 +00:00
Matthias Krüger
4b6a22d05c
Rollup merge of #138107 - yotamofek:pr/rustdoc/clippy, r=GuillaumeGomez
...
`librustdoc`: clippy fixes
First commit is all machine-generated fixes,
next two are some more lints fixed by hand/misc. cleanups
Inspired by the redundant `.and_then()` added in https://github.com/rust-lang/rust/pull/137320 , and [this comment](https://github.com/rust-lang/rust/pull/138090#discussion_r1983111856 )
r? ```@GuillaumeGomez```
2025-03-07 10:12:47 +01:00
Yotam Ofek
ccfbfe2292
x clippy src/librustdoc --fix
2025-03-06 16:06:41 +00:00
Yotam Ofek
fde37335aa
librustdoc: flatten nested ifs
2025-03-06 08:16:28 +00:00
Michael Howell
61a97448e5
rustdoc: improve refdef handling in the unresolved link lint
...
This commit takes advantage of a feature in pulldown-cmark that
makes the list of link definitions available to the consuming
application. It produces unresolved link warnings for refdefs
that aren't used, and can now produce exact spans for the dest
even when it has escapes.
2025-02-15 12:21:35 -07:00
Jacob Pratt
9fe0d25fcb
Rollup merge of #136927 - GuillaumeGomez:add-missing-hashtag-escape, r=notriddle
...
Correctly escape hashtags when running `invalid_rust_codeblocks` lint
Fixes #136899 .
We forgot to use `map_line` when we wrote this lint.
r? ``@notriddle``
2025-02-12 20:10:01 -05:00
Guillaume Gomez
54f59c6dda
Correctly escape hashtags when running invalid_rust_codeblocks lint
2025-02-12 19:46:07 +01:00
Yotam Ofek
d99d8c249d
Nuke Buffer abstraction from librustdoc 💣
2025-02-12 15:50:06 +00:00
Guillaume Gomez
bdc8df4cb5
Improve rustdoc code
2024-12-25 22:22:23 +01:00
Guillaume Gomez
d03380957b
Fix intra doc links not generated inside footnote definitions
2024-12-17 17:25:19 +01:00
Guillaume Gomez
6e0dabd9e2
Turn markdown_split_summary_and_content into a method of Markdown
2024-12-05 22:50:21 +01:00
Guillaume Gomez
fad5f51183
Always display first line of impl blocks even when collapsed
2024-12-05 22:50:20 +01:00
Guillaume Gomez
b863c0d28b
Remove static HashSet for default IDs list
2024-12-02 12:03:32 +01:00
Guillaume Gomez
2e242f8af3
Store default ID map in a static
2024-12-01 21:54:55 +01:00
Guillaume Gomez
46afbc0588
Split ID maps in two parts: the constant one and the updated one
2024-12-01 21:54:55 +01:00
Guillaume Gomez
8047340599
Stop cloning Context so much
2024-12-01 21:54:54 +01:00
Guillaume Gomez
f0c301ffe4
Fix new clippy lints
2024-11-28 03:05:43 +01:00
Guillaume Gomez
d9aac8cfce
Fix duplicated footnote IDs
2024-11-13 16:56:18 +01:00
Alona Enraght-Moony
ebb842328a
rustdoc: Extract footnote logic into it's own module.
2024-10-19 14:37:11 +00:00
León Orell Valerian Liehr
6d82559bc1
rustdoc: Rename "object safe" to "dyn compatible"
2024-10-16 15:53:49 +02:00
bors
6a3c45e1c6
Auto merge of #131368 - GuillaumeGomez:rustdoc-dead-code, r=notriddle
...
[rustdoc] Remove intra-doc links dead code
While working on https://github.com/rust-lang/rust/pull/130278 , I wondered what `resolve_display_text` was doing. I removed it and ran all rustdoc tests, and nothing failed. Are some intra-doc links tests missing or is it really dead code? Couldn't figure it out.
r? `@notriddle`
2024-10-08 10:07:44 +00:00
Guillaume Gomez
126cb9bb78
Remove dead code
2024-10-07 18:41:32 +02:00
ismailarilik
e0a20b484d
Handle librustdoc cases of rustc::potential_query_instability lint
2024-10-06 10:39:03 +03:00
Guillaume Gomez
6f5f21adfc
Rename doctest attribute standalone-crate into standalone_crate for coherency
2024-09-29 13:01:41 +02:00
Guillaume Gomez
632fed891d
Improve mistyped docblock attribute warning messages
2024-09-28 18:38:11 +02:00
Guillaume Gomez
0956f69caf
Add warning if standalone-crate is mistyped
2024-09-28 18:38:11 +02:00
Guillaume Gomez
35f24d0d14
Improve code for codeblock invalid attributes
2024-09-28 18:38:11 +02:00
Guillaume Gomez
cdf2a8ffc5
Rename standalone doctest attribute into standalone-crate
2024-09-28 18:38:10 +02:00
Michael Goulet
c682aa162b
Reformat using the new identifier sorting from rustfmt
2024-09-22 19:11:29 -04:00
Guillaume Gomez
7c35266552
Strip last backline from non-rust code examples
2024-09-22 00:18:44 +02:00
Matthias Krüger
e1da72c6e8
Rollup merge of #120736 - notriddle:notriddle/toc, r=t-rustdoc
...
rustdoc: add header map to the table of contents
## Summary
Add header sections to the sidebar TOC.
### Preview
* http://notriddle.com/rustdoc-html-demo-9/toc/rust/std/index.html
* http://notriddle.com/rustdoc-html-demo-9/toc/rust-derive-builder/derive_builder/index.html
## Motivation
Some pages are very wordy, like these.
| crate | word count |
|--|--|
| [std::option](https://doc.rust-lang.org/stable/std/option/index.html ) | 2,138
| [derive_builder](https://docs.rs/derive_builder/0.13.0/derive_builder/index.html ) | 2,403
| [tracing](https://docs.rs/tracing/0.1.40/tracing/index.html ) | 3,912
| [regex](https://docs.rs/regex/1.10.3/regex/index.html ) | 8,412
This kind of very long document is more navigable with a table of contents, like Wikipedia's or the one [GitHub recently added](https://github.blog/changelog/2021-04-13-table-of-contents-support-in-markdown-files/ ) for READMEs.
In fact, the use case is so compelling, that it's been requested multiple times and implemented in an extension:
* https://github.com/rust-lang/rust/issues/80858
* https://github.com/rust-lang/rust/issues/28056
* https://github.com/rust-lang/rust/issues/14475
* https://rust.extension.sh/#show-table-of-content
(Some of these issues ask for more than this, so don’t close them.)
It's also been implemented by hand in some crates, because the author really thought it was needed. Protip: for a more exhaustive list, run [`site:docs.rs table of contents`](https://duckduckgo.com/?t=ffab&q=site%3Adocs.rs+table+of+contents&ia=web ), though some of them are false positives.
* https://docs.rs/figment/0.10.14/figment/index.html#table-of-contents
* https://docs.rs/csv/1.3.0/csv/tutorial/index.html#table-of-contents
* https://docs.rs/axum/0.7.4/axum/response/index.html#table-of-contents
* https://docs.rs/regex-automata/0.4.5/regex_automata/index.html#table-of-contents
Unfortunately for these hand-built ToCs, because they're just part of the docs, there's no consistent way to turn them off if the reader doesn't want them. It's also more complicated to ensure they stay in sync with the docs they're supposed to describe, and they don't stay with you when you scroll like Wikipedia's [does now](https://uxdesign.cc/design-notes-on-the-2023-wikipedia-redesign-d6573b9af28d ).
## Guide-level explanation
When writing docs for a top-level item, the first and second level of headers will be shown in an outline in the sidebar. In this context, "top level" means "not associated".
This means, if you're writing very long guides or explanations, and you want it to have a table of contents in the sidebar for its headings, the ideal place to attach it is usually the *module* or *crate*, because this page has fewer other things on it (and is the ideal place to describe "cross-cutting concerns" for its child items).
If you're reading documentation, and want to get rid of the table of contents, open the  Settings panel and checkmark "Hide table of contents."
## Reference-level explanation
Top-level items have an outline generated. This works for potentially-malformed header trees by pairing a header with the nearest header with a higher level. For example:
```markdown
## A
# B
# C
## D
## E
```
A, B, and C are all siblings, and D and E are children of C.
Rustdoc only presents two layers of tree, but it tracks up to the full depth of 6 while preparing it.
That means that these two doc comment both generate the same outline:
```rust
/// # First
/// ## Second
struct One;
/// ## First
/// ### Second
struct Two;
```
## Drawbacks
The biggest drawback is adding more stuff to the sidebar.
My crawl through docs.rs shows this to, surprisingly, be less of a problem than I thought. The manually-built tables of contents, and the pages with dozens of headers, usually seem to be modules or crates, not types (where extreme scrolling would become a problem, since they already have methods to deal with).
The best example of a type with many headers is [vec::Vec](https://doc.rust-lang.org/1.75.0/std/vec/struct.Vec.html ), which still only has five headers, not dozens like [axum::extract](https://docs.rs/axum/0.7.4/axum/extract/index.html ).
## Rationale and alternatives
### Why in the existing sidebar?
The method links and the top-doc header links have more in common with each other than either of them do with the "In [parent module]" links, and should go together.
### Why limited to two levels?
The sidebar is pretty narrow, and I don't want too much space used by indentation. Making the sidebar wider, while it has some upsides, also takes up more space on middling-sized screens or tiled WMs.
### Why not line wrap?
That behaves strangely when resizing.
## Prior art
### Doc generators that have TOC for headers
https://hexdocs.pm/phoenix/Phoenix.Controller.html is very close, in the sense that it also has header sections directly alongside functions and types.
Another example, referenced as part of the [early sidebar discussion](https://github.com/rust-lang/rust/issues/37856 ) that added methods, Ruby will show a table of contents in the sidebar (for example, on the [ARGF](https://docs.ruby-lang.org/en/master/ARGF.html ) class). According to their changelog, [they added it in 2013](06137bde8c/History.rdoc (400--2013-02-24-)https://hackage.haskell.org/package/base-4.19.0.0/docs/Control-Monad.html#g:3 ) is plain text, and is immediately followed by functions. And the [Pandoc top level](https://hackage.haskell.org/package/pandoc-3.1.11.1/docs/Text-Pandoc.html ) has items split up by function, rather than by kind. Their TOC matches exactly with the contents of the page.
### Doc generators that don't have header TOC, but still have headers
Elm, interestingly enough, seems to have the same setup that Rust used to have: sibling navigation between modules, and no index within a single page. [They keep Haskell's habit of named sections with machine-generated type signatures](https://package.elm-lang.org/packages/elm/browser/latest/Browser-Dom ), though.
[PHP](https://www.php.net/manual/en/book.datetime.php ), like elm, also has a right-hand sidebar with sibling navigation. However, PHP has a single page for a single method, unlike Rust's page for an entire "class." So even though these pages have headers, it's never more than ten at most. And when they have guides, those guides are also multi-page.
## Unresolved questions
* Writing recommendations for anyone who wants to take advantage of this.
* Right now, it does not line wrap. That might be a bad idea: a lot of these are getting truncated.
* Split sidebars, which I [tried implementing](https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/Table.20of.20contents ), are not required. The TOC can be turned off, if it's really a problem. Implemented in https://github.com/rust-lang/rust/pull/120818 , but needs more, separate, discussion.
## Future possibilities
I would like to do a better job of distinguishing global navigation from local navigation. Rustdoc has a pretty reasonable information architecture, if only we did a better job of communicating it.
This PR aims, mostly, to help doc authors help their users by writing docs that can be more effectively skimmed. But it doesn't do anything to make it easier to tell the TOC and the Module Nav apart.
2024-09-05 03:47:40 +02:00
Nicholas Nethercote
37d1ce91b5
Remove #[macro_use] extern crate tracing from rustdoc.
2024-08-30 13:16:08 +10:00
Michael Howell
12a3c42ccc
rustdoc: consistentify #TOC and #ModNav to lowercase
2024-08-20 16:51:40 -07:00
Michael Howell
7091fa5880
rustdoc: show code spans as <code> in TOC
2024-08-20 16:51:37 -07:00
