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

bootstrap: document how to reproduce broken intra-doc links locally #109190

Open
peter-lyons-kehl opened this issue Mar 15, 2023 · 2 comments
Open
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap)

Comments

@peter-lyons-kehl
Copy link
Contributor

peter-lyons-kehl commented Mar 15, 2023

Neither x test tidy --bless, nor x test tidy --doc, report incorrect links from /// rustdocs. Example:

  1. Incorrect/unregistered markdown link shortcut, and/or broken intradoc code link:
    https://github.com/rust-lang/rust/actions/runs/4429807104/jobs/7770725259#step:26:2652
     |     /// Like [from_iter], but coallocation-aware.
     |               ^^^^^^^^^ no item named `from_iter` in scope
     |
     = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
     = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`
  1. URLs not made into links:
    https://github.com/rust-lang/rust/actions/runs/4429807104/jobs/7770725259#step:26:2704
49 | /// Workaround https://github.com/rust-lang/rust/issues/108751
   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<https://github.com/rust-lang/rust/issues/108751>`

Please, either

  • make (local) tidy report the above, or
  • add steps (to the documentation) on how to check the above locally.

Side notes

Thank you in advance.

@peter-lyons-kehl
Copy link
Contributor Author

peter-lyons-kehl commented Mar 15, 2023

I see, it's x doc library/alloc, or ./x.py doc library/alloc (or similar for other libraries etc.).

Unfortunately, that is not obvious. I'll dig around rustc-dev-guide for where this could be mentioned more.

@clubby789
Copy link
Contributor

@rustbot label +T-bootstrap

@rustbot rustbot added the T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) label Mar 27, 2023
@jyn514 jyn514 added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Apr 5, 2023
@jyn514 jyn514 changed the title tidy doesn't report incorrect links from /// rustdoc bootstrap: document how to reproduce broken intra-doc links locally Apr 5, 2023
@jyn514 jyn514 added the A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name label Apr 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap)
Projects
None yet
Development

No branches or pull requests

4 participants