Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rollup of 7 pull requests #129976

Closed
wants to merge 24 commits into from
Closed

Conversation

tgross35
Copy link
Contributor

@tgross35 tgross35 commented Sep 5, 2024

Successful merges:

Failed merges:

r? @ghost
@rustbot modify labels: rollup

Create a similar rollup

Noratrieb and others added 24 commits July 7, 2024 13:42
Because it's the target libdir.

`--print` uses the same terminology, and it's a simple way to make it
obviously different from `$sysroot/lib`.
This commit adds the headers for the top level documentation to
rustdoc's existing table of contents, along with associated items.

It only show two levels of headers. Going further would require the
sidebar to be wider, and that seems unnecessary (the crates that
have manually-built TOCs usually don't need deeply nested headers).
…jieyouxu,petrochenkov

Update mingw-w64 + GNU toolchain

The list of packaged tools and their versions is available at: https://github.com/niXman/mingw-builds-binaries/releases/tag/14.1.0-rt_v12-rev0

Fixes: rust-lang#112368
rustdoc: add header map to the table of contents

## Summary

Add header sections to the sidebar TOC.

### Preview

![image](https://github.com/user-attachments/assets/eae4df02-86aa-4df4-8c61-a95685cd8829)

* 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:

* rust-lang#80858
* rust-lang#28056
* rust-lang#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 ![image](https://github.com/rust-lang/rust/assets/1593513/2ad82466-5fe3-4684-b1c2-6be4c99a8666) 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](rust-lang#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 rust-lang#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.
…-ozkan

Call the target libdir target libdir

Because it's the target libdir.

`--print` uses the same terminology, and it's a simple way to make it obviously different from `$sysroot/lib`.
…llot

Add an internal lint that warns when accessing untracked data

Some methods access data that is not tracked by the query system and should be used with caution. As suggested in rust-lang#128815 (comment), in this PR I propose a lint (modeled on the `potential_query_instability` lint) that warns when using some specially-annotatted functions.

I can't tell myself if this lint would be that useful, compared to renaming `Steal::is_stolen` to `is_stolen_untracked`. This would depend on whether there are other functions we'd want to lint like this. So far it seems they're called `*_untracked`, which may be clear enough.

r? `@oli-obk`
… r=albertlarsan68

warn the user if the upstream master branch is old

fixes rust-lang#129528
…tmcm

clarify that addr_of creates read-only pointers

Stacked Borrows does make this UB, but Tree Borrows does not. This is tied up with rust-lang#56604 and other UCG discussions. Also see [this collection of links](Rust-for-Linux/linux#950 (comment)) where rustc treats `addr_of!` as a "non-mutating use".

So, let's better be careful for now.
@rustbot rustbot added A-testsuite Area: The testsuite used to check the correctness of rustc S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Sep 5, 2024
@rustbot rustbot added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. rollup A PR which is a rollup labels Sep 5, 2024
@tgross35
Copy link
Contributor Author

tgross35 commented Sep 5, 2024

@bors r+ rollup=never p=7

@bors
Copy link
Contributor

bors commented Sep 5, 2024

📌 Commit d5d83a8 has been approved by tgross35

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 5, 2024
@rust-log-analyzer
Copy link
Collaborator

The job mingw-check-tidy failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
COPY host-x86_64/mingw-check/validate-error-codes.sh /scripts/

# NOTE: intentionally uses python2 for x.py so we can test it still works.
# validate-toolstate only runs in our CI, so it's ok for it to only support python3.
ENV SCRIPT TIDY_PRINT_DIFF=1 python2.7 ../x.py test \
           --stage 0 src/tools/tidy tidyselftest --extra-checks=py:lint,cpp:fmt
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --allow-unsafe --generate-hashes reuse-requirements.in
---
#13 2.759 Building wheels for collected packages: reuse
#13 2.760   Building wheel for reuse (pyproject.toml): started
#13 3.005   Building wheel for reuse (pyproject.toml): finished with status 'done'
#13 3.006   Created wheel for reuse: filename=reuse-4.0.3-cp310-cp310-manylinux_2_35_x86_64.whl size=132715 sha256=dfa09868353292d98f811d3efdb0d54d07389e808efc71d68e3b93c514bf8bec
#13 3.007   Stored in directory: /tmp/pip-ephem-wheel-cache-qm36k7kx/wheels/3d/8d/0a/e0fc6aba4494b28a967ab5eaf951c121d9c677958714e34532
#13 3.009 Installing collected packages: boolean-py, binaryornot, tomlkit, reuse, python-debian, markupsafe, license-expression, jinja2, chardet, attrs
#13 3.407 Successfully installed attrs-23.2.0 binaryornot-0.4.4 boolean-py-4.0 chardet-5.2.0 jinja2-3.1.4 license-expression-30.3.0 markupsafe-2.1.5 python-debian-0.1.49 reuse-4.0.3 tomlkit-0.13.0
#13 3.408 WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
#13 3.934 Collecting virtualenv
#13 3.934 Collecting virtualenv
#13 3.992   Downloading virtualenv-20.26.3-py3-none-any.whl (5.7 MB)
#13 4.079      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5.7/5.7 MB 66.8 MB/s eta 0:00:00
#13 4.132 Collecting platformdirs<5,>=3.9.1
#13 4.141   Downloading platformdirs-4.2.2-py3-none-any.whl (18 kB)
#13 4.160 Collecting distlib<1,>=0.3.7
#13 4.177      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 468.9/468.9 KB 72.7 MB/s eta 0:00:00
#13 4.211 Collecting filelock<4,>=3.12.2
#13 4.220   Downloading filelock-3.15.4-py3-none-any.whl (16 kB)
#13 4.220   Downloading filelock-3.15.4-py3-none-any.whl (16 kB)
#13 4.302 Installing collected packages: distlib, platformdirs, filelock, virtualenv
#13 4.498 Successfully installed distlib-0.3.8 filelock-3.15.4 platformdirs-4.2.2 virtualenv-20.26.3
#13 DONE 4.6s

#14 [7/8] COPY host-x86_64/mingw-check/validate-toolstate.sh /scripts/
#14 DONE 0.0s
---
   Compiling build_helper v0.1.0 (/checkout/src/tools/build_helper)
error[E0599]: no method named `sysroot_libdir` found for reference `&core::builder::Builder<'_>` in the current scope
##[error]    --> src/core/build_steps/dist.rs:478:39
     |
478  |                 let src_dir = builder.sysroot_libdir(compiler, host).parent().unwrap().join("bin");
     |
help: there is a method `sysroot` with a similar name, but with different arguments
    --> src/core/builder.rs:1149:5
     |
---
   Compiling bootstrap v0.0.0 (/checkout/src/bootstrap)
error[E0599]: no method named `sysroot_libdir` found for reference `&core::builder::Builder<'_>` in the current scope
##[error]    --> src/core/build_steps/dist.rs:478:39
     |
478  |                 let src_dir = builder.sysroot_libdir(compiler, host).parent().unwrap().join("bin");
     |
help: there is a method `sysroot` with a similar name, but with different arguments
    --> src/core/builder.rs:1149:5
     |
---
   Compiling bootstrap v0.0.0 (/checkout/src/bootstrap)
error[E0599]: no method named `sysroot_libdir` found for reference `&core::builder::Builder<'_>` in the current scope
##[error]    --> src/core/build_steps/dist.rs:478:39
     |
478  |                 let src_dir = builder.sysroot_libdir(compiler, host).parent().unwrap().join("bin");
     |
help: there is a method `sysroot` with a similar name, but with different arguments
    --> src/core/builder.rs:1149:5
     |
---
   Compiling bootstrap v0.0.0 (/checkout/src/bootstrap)
error[E0599]: no method named `sysroot_libdir` found for reference `&core::builder::Builder<'_>` in the current scope
##[error]    --> src/core/build_steps/dist.rs:478:39
     |
478  |                 let src_dir = builder.sysroot_libdir(compiler, host).parent().unwrap().join("bin");
     |
help: there is a method `sysroot` with a similar name, but with different arguments
    --> src/core/builder.rs:1149:5
     |
---
   Compiling bootstrap v0.0.0 (/checkout/src/bootstrap)
error[E0599]: no method named `sysroot_libdir` found for reference `&core::builder::Builder<'_>` in the current scope
##[error]    --> src/core/build_steps/dist.rs:478:39
     |
478  |                 let src_dir = builder.sysroot_libdir(compiler, host).parent().unwrap().join("bin");
     |
help: there is a method `sysroot` with a similar name, but with different arguments
    --> src/core/builder.rs:1149:5
     |

@tgross35 tgross35 closed this Sep 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-testsuite Area: The testsuite used to check the correctness of rustc rollup A PR which is a rollup S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. T-libs Relevant to the library team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.