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

rustdoc: use more precise relative URLs #83237

Merged
merged 4 commits into from
Apr 17, 2021
Merged

Conversation

notriddle
Copy link
Contributor

@notriddle notriddle commented Mar 17, 2021

This is a fairly large diff, and will probably conflict with #82815 since it reduces (but does not eliminate) the use of the old depth variable.

Instead of using a depth counter and adding "../" to get to the top, this commit makes rustdoc actually compare the path of what it's linking from to the path that it's linking to. This makes the resulting HTML shorter.

Here's a comparison of one of the largest (non-source) files in the Rust standard library docs (about 4% improvement before gzipping).

$ wc -c struct.Wrapping.old.html struct.Wrapping.new.html
2387389 struct.Wrapping.old.html
2298538 struct.Wrapping.new.html

Most if it can be efficiently gzipped away.

$ wc -c struct.Wrapping.old.html.gz struct.Wrapping.new.html.gz
70679 struct.Wrapping.old.html.gz
70050 struct.Wrapping.new.html.gz

But it also makes a difference in the final DOM size, reducing it from 91MiB to 82MiB.

@rust-highfive
Copy link
Collaborator

r? @jyn514

(rust-highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 17, 2021
@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@camelid camelid added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Mar 21, 2021
@bors

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@bors

This comment has been minimized.

@notriddle notriddle force-pushed the short-links branch 3 times, most recently from e734e40 to 93c2e3e Compare March 26, 2021 08:00
@bors

This comment has been minimized.

@bors

This comment has been minimized.

Copy link
Member

@jyn514 jyn514 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But it also makes a difference in the final DOM size, reducing it from 91MiB to 82MiB.

What is the "DOM size"? Is that like the memory the browser uses the render the page?

I guess before I go much further I should ask: what happens if relative_to is empty? Will it just use links that are relative to the output root? If so I don't feel as bad about bugs, it just means the links are a little more verbose.

src/librustdoc/clean/types.rs Outdated Show resolved Hide resolved
src/librustdoc/clean/types.rs Outdated Show resolved Hide resolved
src/librustdoc/clean/mod.rs Outdated Show resolved Hide resolved
src/librustdoc/clean/utils.rs Outdated Show resolved Hide resolved
src/librustdoc/html/format.rs Outdated Show resolved Hide resolved
src/librustdoc/html/format.rs Outdated Show resolved Hide resolved
src/librustdoc/html/format.rs Outdated Show resolved Hide resolved
@notriddle
Copy link
Contributor Author

@jyn514

What is the "DOM size"? Is that like the memory the browser uses the render the page?

Yes, that's exactly what it is. In Firefox, go into the Dev Tools, then pick the Memory tab, then click the Take Snapshot button (camera icon).

what happens if relative_to is empty? Will it just use links that are relative to the output root?

Yes, that's exactly what it does. I've added a test case for this in src/librustdoc/html/tests.rs.

@notriddle
Copy link
Contributor Author

notriddle commented Apr 5, 2021

@jyn514

Can you add a test case for that to make sure it doesn't regress?

Done in 53df7fc507bb6e48e1aa6588300f29c0ee4d0437

s.trim_end_matches

Done in 25bc0c0d1364a0b0cd7b8ba4742d91e3f7158b15

@rust-log-analyzer

This comment has been minimized.

@notriddle notriddle force-pushed the short-links branch 2 times, most recently from 4b48b32 to 32d6e4c Compare April 5, 2021 23:59
@bors

This comment has been minimized.

Copy link
Member

@jyn514 jyn514 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d85b42a

Could you add a test for linking to decl macros?

In some places you use cx.current; in others you choose a custom relative_to. I think the only difference is that some places are in clean, so cx.current isn't set yet. Rather than threading relative_to through everywhere, do you think it makes sense to set cx.current instead, and remember to unset it when you're done? That would make the diff a lot smaller and also reduce the number of parameters everywhere. You could add a with_current_path function or something to make sure you don't forget to reset it.

src/test/rustdoc/cross-crate-primitive-doc.rs Outdated Show resolved Hide resolved
src/librustdoc/html/format.rs Show resolved Hide resolved
src/librustdoc/html/format.rs Show resolved Hide resolved
src/librustdoc/html/format.rs Show resolved Hide resolved
src/librustdoc/html/format.rs Show resolved Hide resolved
src/librustdoc/html/format.rs Outdated Show resolved Hide resolved
src/librustdoc/html/format.rs Outdated Show resolved Hide resolved
src/librustdoc/html/format.rs Outdated Show resolved Hide resolved
src/librustdoc/html/tests.rs Outdated Show resolved Hide resolved
src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved
@jyn514
Copy link
Member

jyn514 commented Apr 16, 2021

Oh definitely - this PR is fine as-is, I meant in a follow-up.

@jyn514 jyn514 added S-blocked Status: Blocked on something else such as an RFC or other implementation work. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Apr 16, 2021
jyn514 pushed a commit to jyn514/rust that referenced this pull request Apr 16, 2021
… r=jyn514

rustdoc: clean up and test macro visibility print

This fixes the overly-complex invariant mentioned in <rust-lang#83237 (comment)>, where the macro source can't have any links in it only because the cache hasn't been populated yet.
@jyn514
Copy link
Member

jyn514 commented Apr 16, 2021

I opened #84258 to get #84074 and #84246 merged; please wait for that to land (it should hopefully be the last rebase you have to do). I'll be offline the rest of the day and I didn't want you to hit more conflicts overnight :)

Thanks so much for working on this!

@bors delegate=notriddle

@bors
Copy link
Contributor

bors commented Apr 16, 2021

✌️ @notriddle can now approve this pull request

@jyn514 jyn514 marked this pull request as ready for review April 16, 2021 20:17
bors added a commit to rust-lang-ci/rust that referenced this pull request Apr 16, 2021
…=jyn514

rustdoc: clean up and test macro visibility print

This fixes the overly-complex invariant mentioned in <rust-lang#83237 (comment)>, where the macro source can't have any links in it only because the cache hasn't been populated yet.
@bors

This comment has been minimized.

Instead of using a depth counter and adding "../" to get to the top,
this commit makes rustdoc actually compare the path of what it's
linking from to the path that it's linking to. This makes the resulting
HTML shorter.

Here's a comparison of one of the largest (non-source) files in the
Rust standard library docs (about 4% improvement before gzipping).

    $ wc -c struct.Wrapping.old.html struct.Wrapping.new.html
    2387389 struct.Wrapping.old.html
    2298538 struct.Wrapping.new.html

Most if it can be efficiently gzipped away.

    $ wc -c struct.Wrapping.old.html.gz struct.Wrapping.new.html.gz
    70679 struct.Wrapping.old.html.gz
    70050 struct.Wrapping.new.html.gz

But it also makes a difference in the final DOM size, reducing it from 91MiB to 82MiB.
The function `to_src_with_space` doesn't even accept the cache as a parameter,
so it doesn't matter any more what's in it.
This should help make things consistent.
@notriddle
Copy link
Contributor Author

@bors r=jyn514

@bors
Copy link
Contributor

bors commented Apr 17, 2021

📌 Commit 755b4fb has been approved by jyn514

@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-blocked Status: Blocked on something else such as an RFC or other implementation work. labels Apr 17, 2021
bors added a commit to rust-lang-ci/rust that referenced this pull request Apr 17, 2021
Rollup of 4 pull requests

Successful merges:

 - rust-lang#83237 (rustdoc: use more precise relative URLs)
 - rust-lang#84150 (rustdoc: move some search code into search.js)
 - rust-lang#84203 (rustdoc: Give a more accurate span for anchor failures)
 - rust-lang#84257 (Add documentation to help people find `Ipv4Addr::UNSPECIFIED`)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 5dae27a into rust-lang:master Apr 17, 2021
@rustbot rustbot added this to the 1.53.0 milestone Apr 17, 2021
@notriddle notriddle deleted the short-links branch April 17, 2021 23:32
@jyn514
Copy link
Member

jyn514 commented Apr 18, 2021

🎉 🎉 🎉

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Sep 16, 2022
…mp-to-definition, r=GuillaumeGomez

rustdoc: use more precise URLs for jump-to-definition links

As an example, this cuts down <https://doc.rust-lang.org/nightly/nightly-rustc/src/rustc_middle/ty/mod.rs.html> by about 11%.

    $ du -h new_mod.rs.html old_mod.rs.html
    296K	new_mod.rs.html
    332K	old_mod.rs.html

Like rust-lang#83237, but separate code since source links have a different URL structure.

Related to [Zulip discussion](https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/RFC.20for.20.22jump.20to.20definition.22.20feature/near/299029786) and [the jump-to-definition pre-RFC](GuillaumeGomez/rfcs#1).
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Nov 13, 2024
…o-decl, r=notriddle

rustdoc: Treat declarative macros more like other item kinds

Apparently at some time in the past we were unable to generate an href for the module path inside the visibility of decl macros 2.0 (`pub(in ...)`). As a result of this, a whole separate function was introduced specifically for printing the visibility of decl macros that didn't attempt to generate any links. The description of PR rust-lang#84074 states:

> This fixes the overly-complex invariant mentioned in rust-lang#83237 (comment), where the macro source can't have any links in it only because the cache hasn't been populated yet.

I can no longer reproduce the original issue. Reusing the existing visibility rendering logic *seems* to work just fine (I couldn't come up with any counterexamples, though I invite you to prove me wrong).

* Fixes rust-lang#83000
* Fixes the visibility showing up "twice" in rustdoc-JSON output: Once as the `visibility` field, once baked into the source[^1]
* Fixes `#[doc(hidden)]` not getting rendered on doc(hidden) decl macros 2.0 under `--document-hiden-items` (for decl macros 1.2 the issue remains; I will address this separately when fixing rust-lang#132304).

---

<details><summary>Outdated Section</summary>

NOTE: The current version of this PR is committing a UI crime, I'd like to receive feedback on that. Maybe you have a satisfactory solution for how to remedy it. Namely, as you know we have two different ways of / modes for highlighting code with color:

1. Only highlighting links / item paths and avoiding to highlight tokens by kind like keywords (to reduce visual noise and maybe also artifact size). Used for item declarations(\*).
2. Highlighting tokens by kind. Used for code blocks written by the user.

(\*): With the notable exception being macro declarations! Well, since this PR reuses the same function for rendering the item visibility (which only makes sense), we have a clash of modes: We now use both ways of highlighting code for decl macros: №1 for the visibility, №2 for the rest. This awkward. See for yourself:

* On master: ![Screenshot 2024-10-29 at 03-37-48 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/22f0ab6e-9ba9-4c4e-8fb0-0741c91d360b)
* On this branch: ![Screenshot 2024-10-29 at 03-36-41 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/b11d81a3-3e2e-43cb-a5b8-6773a3048732)

</details>

Furthermore, we now no longer syntax-highlight declarative macros (be it `macro_rules!` or `macro`) since that was inconsistent with the way we render all other item kinds. See (collapsed) *Outdated Section* above. See also rust-lang#132302 (comment).

| On master | On this branch |
|---|---|
| ![Screenshot 2024-11-13 at 16-12-46 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/cb3aeb42-a56d-4ced-80d9-f2694f369af1) | ![Screenshot 2024-11-13 at 16-13-22 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/b73bee50-1b85-4862-afba-5ad471443ccc) |

[^1]: E.g., `"visibility":{"restricted":{"parent":1,"path":"::a"}},/*OMITTED*/,"inner":{"macro":"pub(in a) macro by_example_vis_named($foo:expr) {\n    ...\n}"}`
rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Nov 14, 2024
Rollup merge of rust-lang#132302 - fmease:rustdoc-better-vis-for-macro-decl, r=notriddle

rustdoc: Treat declarative macros more like other item kinds

Apparently at some time in the past we were unable to generate an href for the module path inside the visibility of decl macros 2.0 (`pub(in ...)`). As a result of this, a whole separate function was introduced specifically for printing the visibility of decl macros that didn't attempt to generate any links. The description of PR rust-lang#84074 states:

> This fixes the overly-complex invariant mentioned in rust-lang#83237 (comment), where the macro source can't have any links in it only because the cache hasn't been populated yet.

I can no longer reproduce the original issue. Reusing the existing visibility rendering logic *seems* to work just fine (I couldn't come up with any counterexamples, though I invite you to prove me wrong).

* Fixes rust-lang#83000
* Fixes the visibility showing up "twice" in rustdoc-JSON output: Once as the `visibility` field, once baked into the source[^1]
* Fixes `#[doc(hidden)]` not getting rendered on doc(hidden) decl macros 2.0 under `--document-hiden-items` (for decl macros 1.2 the issue remains; I will address this separately when fixing rust-lang#132304).

---

<details><summary>Outdated Section</summary>

NOTE: The current version of this PR is committing a UI crime, I'd like to receive feedback on that. Maybe you have a satisfactory solution for how to remedy it. Namely, as you know we have two different ways of / modes for highlighting code with color:

1. Only highlighting links / item paths and avoiding to highlight tokens by kind like keywords (to reduce visual noise and maybe also artifact size). Used for item declarations(\*).
2. Highlighting tokens by kind. Used for code blocks written by the user.

(\*): With the notable exception being macro declarations! Well, since this PR reuses the same function for rendering the item visibility (which only makes sense), we have a clash of modes: We now use both ways of highlighting code for decl macros: №1 for the visibility, №2 for the rest. This awkward. See for yourself:

* On master: ![Screenshot 2024-10-29 at 03-37-48 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/22f0ab6e-9ba9-4c4e-8fb0-0741c91d360b)
* On this branch: ![Screenshot 2024-10-29 at 03-36-41 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/b11d81a3-3e2e-43cb-a5b8-6773a3048732)

</details>

Furthermore, we now no longer syntax-highlight declarative macros (be it `macro_rules!` or `macro`) since that was inconsistent with the way we render all other item kinds. See (collapsed) *Outdated Section* above. See also rust-lang#132302 (comment).

| On master | On this branch |
|---|---|
| ![Screenshot 2024-11-13 at 16-12-46 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/cb3aeb42-a56d-4ced-80d9-f2694f369af1) | ![Screenshot 2024-11-13 at 16-13-22 by_example_vis_named in decl_macro a b c - Rust](https://github.com/user-attachments/assets/b73bee50-1b85-4862-afba-5ad471443ccc) |

[^1]: E.g., `"visibility":{"restricted":{"parent":1,"path":"::a"}},/*OMITTED*/,"inner":{"macro":"pub(in a) macro by_example_vis_named($foo:expr) {\n    ...\n}"}`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. 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.

7 participants