| Age | Commit message (Collapse) | Author | Lines |
|---|
|
|
|
|
|
Generate scraped examples buttons in JS
Follow-up of https://github.com/rust-lang/rust/pull/129796.
To reduce the page size when there are scraped examples, we can generate their buttons in JS since they require JS to work in any case. There should be no changes in display or in functionality.
You can test it [here](https://rustdoc.crud.net/imperio/gen-scraped-buttons/doc/scrape_examples/fn.test.html).
cc `@willcrichton`
r? `@notriddle`
|
|
- Replace non-standard names like 's, 'p, 'rg, 'ck, 'parent, 'this, and
'me with vanilla 'a. These are cases where the original name isn't
really any more informative than 'a.
- Replace names like 'cx, 'mir, and 'body with vanilla 'a when the lifetime
applies to multiple fields and so the original lifetime name isn't
really accurate.
- Put 'tcx last in lifetime lists, and 'a before 'b.
|
|
|
|
This tweaks it to use less space for the breadcrumbs.
|
|
This adds labels to the icons and moves them away from the search box.
These changes are made together, because they work together, but are based on
several complaints:
* The [+/-] thing are a Reddit-ism. They don't look like buttons, but look
like syntax
<https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/More.20visual.20difference.20for.20the.20.2B.2F-.20.20Icons>,
<https://github.com/rust-lang/rust/issues/59851>
(some of these are laundry lists with more suggestions, but they all
mention [+/-] looking wrong)
* The settings, help, and summary buttons are also too hard to recognize
<https://lwn.net/Articles/987070/>,
<https://github.com/rust-lang/rust/issues/90310>,
<https://github.com/rust-lang/rust/issues/14475#issuecomment-274241997>,
<https://internals.rust-lang.org/t/improve-rustdoc-design/12758>
("Not all functionality is self-explanatory, for example the [+] button in
the top right corner, the theme picker or the settings button.")
The toggle-all and toggle-individual buttons both need done at once, since we
want them to look like they go together. This changes them from both being
[+/-] to both being arrows.
Settings and Help are also migrated, so that the whole group can benefit from
being described using actual words.
Additionally, the Help button is only shown on SERPs, not all the time.
This is done for two major reasons:
* Most of what's in there is search-related. The things that aren't are
keyboard commands, and the search box tells you about that anyway.
Pressing <kbd>?</kbd> will temporarily show the button and its popover.
* I'm trading it off by showing the help button, even on mobile.
It's useful since you can use the search engine suggestions there.
* The three buttons were causing line wrapping on too many desktop layouts.
|
|
rustdoc rfc#3662 changes under unstable flags
* All new functionality is under unstable options
* Adds `--merge=shared|none|finalize` flags
* Adds `--parts-out-dir=<crate specific directory>` for `--merge=none`
to write cross-crate info file for a single crate
* Adds `--include-parts-dir=<previously specified directory>` for
`--merge=finalize` to write cross-crate info files
* `tests/rustdoc/` tests for the new flags
|
|
|
|
* All new functionality is under unstable options
* Adds `--merge=shared|none|finalize` flags
* Adds `--parts-out-dir=<crate specific directory>` for `--merge=none`
to write cross-crate info file for a single crate
* Adds `--include-parts-dir=<previously specified directory>` for
`--merge=finalize` to write cross-crate info files
* update tests/run-make/rustdoc-default-output/rmake.rs golden
|
|
r=lolbinarycat,GuillaumeGomez
rustdoc-search: allow trailing `Foo ->` arg search
Fixes #129710
|
|
Implement raw lifetimes and labels (`'r#ident`)
This PR does two things:
1. Reserve lifetime prefixes, e.g. `'prefix#lt` in edition 2021.
2. Implements raw lifetimes, e.g. `'r#async` in edition 2021.
This PR additionally extends the `keyword_idents_2024` lint to also check lifetimes.
cc `@traviscross`
r? parser
|
|
|
|
Use `DeepRejectCtxt` to quickly reject `ParamEnv` candidates
The description is on the [zulip thread](https://rust-lang.zulipchat.com/#narrow/stream/144729-t-types/topic/.5Basking.20for.20help.5D.20.60DeepRejectCtxt.60.20for.20param.20env.20candidates)
r? `@lcnr`
|
|
|
|
|
|
Unify scraped examples with other code examples
Fixes #129763.
This first PR both fixes #129763 but also unifies buttons display for code examples:
You can test it [here](https://rustdoc.crud.net/imperio/unify-code-examples/doc/scrape_examples/fn.test.html) and [here](https://rustdoc.crud.net/imperio/unify-code-examples/doc/scrape_examples/fn.test_many.html).
I'm planning to send a follow-up to make the buttons generated in JS directly (or I can do it in this PR directly if you prefer).
cc ```@willcrichton```
r? ```@notriddle```
|
|
|
|
|
|
|
|
|
|
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](https://github.com/ruby/rdoc/blob/06137bde8ccc48cd502bc28178bcd8f2dfe37624/History.rdoc#400--2013-02-24-).
Haskell seems to mix text and functions even more freely than Elixir. For example, this [Naming conventions](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.
|
|
|
|
|
|
|
|
of the code block
|
|
doc: Make block of inline Deref methods foldable
After:
Before:
Fix #127470.
Current status:
- [x] Bug when hovering over title "Methods from ...": The anchor sign $ overlaps with `[-]`: https://github.com/rust-lang/rust/pull/127474#issuecomment-2222930038
=> Fixed by https://github.com/rust-lang/rust/pull/127474#issuecomment-2228886292
|
|
|
|
|
|
|
|
|
|
Rollup of 11 pull requests
Successful merges:
- #128523 (Add release notes for 1.81.0)
- #129605 (Add missing `needs-llvm-components` directives for run-make tests that need target-specific codegen)
- #129650 (Clean up `library/profiler_builtins/build.rs`)
- #129651 (skip stage 0 target check if `BOOTSTRAP_SKIP_TARGET_SANITY` is set)
- #129684 (Enable Miri to pass pointers through FFI)
- #129762 (Update the `wasm-component-ld` binary dependency)
- #129782 (couple more crash tests)
- #129816 (tidy: say which feature gate has a stability issue mismatch)
- #129818 (make the const-unstable-in-stable error more clear)
- #129824 (Fix code examples buttons not appearing on click on mobile)
- #129826 (library: Fix typo in `core::mem`)
r? `@ghost`
`@rustbot` modify labels: rollup
|
|
r=notriddle
Fix code examples buttons not appearing on click on mobile
When browsing docs on mobile today, I realized that the buttons didn't appear when I tapped on the code example.
One issue: I have no idea how to add a regression test for this case...
r? ``@notriddle``
|
|
|
|
r=GuillaumeGomez
Remove `#[macro_use] extern crate tracing` from rustdoc and rustfmt
A follow-up to #129767 and earlier PRs doing this for `rustc_*` crates.
r? ```@GuillaumeGomez```
|
|
Separate core search logic with search ui
Currenty, the `search.js` mixed with UI/DOM manipulation codes and search logic codes, I propose to extract the search logic to a class for following benefits:
- Clean code. Separation of DOM manipulation and search logic can lead better code maintainability and easy code testings.
- Easy share the search logic for third party to utilize the search function, such as [Rust Search Extension](https://rust.extension.sh), https://query.rs.
This PR added a new class called `DocSearch`, which mainly expose following methods:
```js
class DocSearch {
// Dependency inject searchIndex, rootPath and searchState
constructor(rawSearchIndex, rootPath, searchState) {
// build search index...
}
static parseQuery(userQuery) {
}
async execQuery(parsedQuery, filterCrates, currentCrate) {
}
}
```
|
|
|
|
|
|
Fix rustdoc clippy lints
Ran clippy on rustdoc and fixed the errors.
r? `@notriddle`
|
|
|
|
|
|
Fixes a regression introduced in #128252.
|
|
r=notriddle
[rustdoc] Generate source link on impl associated types
Currently, impl associated types are generated but don't get a source link. This PR fixes that.
Before:
After:
r? `@notriddle`
|
|
r=GuillaumeGomez
rustdoc: clean up tuple <-> primitive conversion docs
This adds a minor missing feature to `fake_variadic`, so that it can render `impl From<(T,)> for [T; 1]` correctly.
|
|
|
|
rustdoc: show exact case-sensitive matches first
fixes #119480
|
|
This adds a minor missing feature to `fake_variadic`,
so that it can render `impl From<(T,)> for [T; 1]` correctly.
|
|
fixes #119480
|
|
File size
---------
```console
$ du -hs doc.old/search-index1.82.0.js doc/search-index1.82.0.js
3.2M doc.old/search-index1.82.0.js
2.8M doc/search-index1.82.0.js
$ gzip doc/search-index1.82.0.js
$ gzip doc.old/search-index1.82.0.js
$ du -hs doc.old/search-index1.82.0.js.gz doc/search-index1.82.0.js.gz
464K doc.old/search-index1.82.0.js.gz
456K doc/search-index1.82.0.js.gz
$ du -hs compiler-doc.old/search-index.js compiler-doc/search-index.js
8.5M compiler-doc.old/search-index.js
6.5M compiler-doc/search-index.js
$ gzip compiler-doc/search-index1.82.0.js
$ gzip compiler-doc.old/search-index1.82.0.js
$ du -hs compiler-doc.old/search-index.js.gz compiler-doc/search-index.js.gz
1.4M compiler-doc.old/search-index.js.gz
1.4M compiler-doc/search-index.js.gz
```
|
|
r=GuillaumeGomez
rustdoc: animate the `:target` highlight
This approach is, roughly, based on how Discourse does it. It came up while discussing [some other possible sidebar changes](https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/Moving.20deprecated.20items.20out.20of.20the.20way), as a design that made rapid scanning easier while avoiding the inherent trade-offs in summarizing.
https://github.com/user-attachments/assets/f7a8fec3-70a5-40a1-92ea-bfdffbd61c22
|
