Commit Graph

206 Commits

Author SHA1 Message Date
Matthias Krüger
6687e8e460
Rollup merge of #119746 - notriddle:notriddle/resize-close-modals, r=fmease
rustdoc: hide modals when resizing the sidebar

Follow-up for
https://github.com/rust-lang/rust/pull/119477#discussion_r1439085011

CC `@lukas-code`
2024-01-22 07:56:42 +01:00
Matthias Krüger
cad609d9e3
Rollup merge of #117662 - GuillaumeGomez:links-in-headings, r=notriddle
[rustdoc] Allows links in headings

Reopening of https://github.com/rust-lang/rust/pull/94360.

# Explanations

Rustdoc currently doesn't follow the markdown spec on headings: we don't allow links in them. So instead of having headings linking to themselves, this PR generates an anchor on the left side like this:

![image](https://github.com/rust-lang/rust/assets/3050060/a118a7e9-5ef8-4d07-914f-46defc3245c3)

<details>
<summary>previous version</summary>

![image](https://github.com/rust-lang/rust/assets/3050060/c34fa844-9cd4-47dc-bb51-b37f5f66afee)

</details>

Having the anchor always displayed allows for mobile devices users to be able to have a link to the anchor. The different color used for the anchor itself is the same as links so people notice when looking at it that they can click on it.

You can test it [here](https://rustdoc.crud.net/imperio/links-in-headings/std/index.html).

cc `@camelid`
r? `@notriddle`
2024-01-19 19:26:59 +01:00
Michael Howell
8b52275ee3 rustdoc: hide modals when resizing the sidebar
Follow-up for
https://github.com/rust-lang/rust/pull/119477#discussion_r1439085011
2024-01-08 09:54:05 -07:00
Lukas Markeffsky
d796ad4209 rustdoc ui: adjust tooltip z-index to be above sidebar 2023-12-31 20:31:56 +01:00
bors
67b6975051 Auto merge of #119066 - notriddle:notriddle/sidebar-source-redesign, r=GuillaumeGomez
rustdoc: clean up source sidebar hide button

This is a redesign of the feature, with parts pulled from https://github.com/rust-lang/rust/pull/119049 but with a button that looks more like a button and matches the one used on other sidebar pages.

Preview:

* http://notriddle.com/rustdoc-html-demo-8/source-sidebar-resize/src/std/lib.rs.html
* http://notriddle.com/rustdoc-html-demo-8/source-sidebar-resize/std/index.html

| | Before | After |
|--|--|--|
| Closed | ![image](https://github.com/rust-lang/rust/assets/1593513/092bed75-79c3-412f-8e7b-557f30dfb1e3) | ![image](https://github.com/rust-lang/rust/assets/1593513/b68e1ee9-9aef-484d-a5b1-2fd29c9d72ea)
| Open | ![image](https://github.com/rust-lang/rust/assets/1593513/95cf9545-25b1-48ec-820b-02e1aec99839) | ![image](https://github.com/rust-lang/rust/assets/1593513/923532f6-59e0-4d7c-9976-21699c30d42e)
| Mobile Closed | ![image](https://github.com/rust-lang/rust/assets/1593513/9bc00cc5-937c-4120-94be-94c7cb6d5297) | ![image](https://github.com/rust-lang/rust/assets/1593513/76a744d8-aac2-46fe-abb9-3b34e2d3ccaa)
| Mobile Open | ![image](https://github.com/rust-lang/rust/assets/1593513/d19a94fe-47b1-462d-a280-44fc215b9b72) | ![image](https://github.com/rust-lang/rust/assets/1593513/2b2e3dec-b610-4b12-8a72-35b86359ba45)
2023-12-31 15:32:15 +00:00
Michael Howell
624885d242 rustdoc: treat query string + as space
Fixes #119219
2023-12-26 14:14:28 -07:00
Guillaume Gomez
98b71bf345 Add GUI regression test for position of warning block 2023-12-24 19:24:04 +01:00
Michael Howell
9566db1e49 Fix corner cases when dealing with mobile mode 2023-12-19 19:50:53 -07:00
Michael Howell
34984a6830 Use folder icon instead of hamburger and sidebar 2023-12-18 18:22:35 -07:00
Michael Howell
c3e29ea5e9 Stop using the trigram of heaven as a hamburger button
It doesn't look quite right, because the lines are too far apart,
and it's not going to be announced by screenreaders as a menu button,
since that's not what the symbol means.

This adds a real tooltip and uses a better drawing of the icon.
2023-12-18 13:56:55 -07:00
Michael Howell
bd14fb68da Add back the column 2023-12-18 12:42:24 -07:00
Michael Howell
859bbc5def rustdoc: clean up source sidebar hide button
This is a redesign of the feature, with parts pulled from
https://github.com/rust-lang/rust/pull/119049
but with a button that looks more like a button and matches the
one used on other sidebar pages.
2023-12-17 23:06:31 -07:00
Matthias Krüger
5fc9ff5619
Rollup merge of #118988 - notriddle:notriddle/varconst, r=GuillaumeGomez
rustdoc: add regression test for JS data file loading

Follow up for #118961
2023-12-15 20:19:56 +01:00
Michael Howell
6bbbff5189 rustdoc: add regression test for JS data file loading
Follow up for #118961
2023-12-15 08:56:49 -07:00
Guillaume Gomez
f8b92697a1
Rollup merge of #115660 - notriddle:notriddle/sidebar-resize, r=GuillaumeGomez
rustdoc: allow resizing the sidebar / hiding the top bar

Fixes #97306

Preview: http://notriddle.com/rustdoc-html-demo-4/sidebar-resize/std/index.html

![image](https://github.com/rust-lang/rust/assets/1593513/a2f40ea2-0436-4e44-99e8-d160dab2a680)

## Summary

This feature adds:

1. A checkbox to the Settings popover to hide the persistent navigation bar (the sidebar on large viewports and the top bar on small ones).
2. On large viewports, it adds a resize handle to the persistent sidebar. Resizing it into nothing is equivalent to turning off the persistent navigation bar checkbox in Settings.
3. If the navigation bar is hidden, a toolbar button to the left of the search appears. Clicking it brings the navigation bar back.

## Motivation

While "mobile mode" is definitely a good default, it's not the only reason people have wanted to hide the sidebar:

* Some people use tiling window managers, and don't like rustdoc's current breakpoints. Changing the breakpoints might help with that, but there's no perfect solution, because there's a gap between "huge screen" and "smartphone" where reasonable people can disagree about whether it makes sense for the sidebar to be on-screen. https://github.com/rust-lang/rust/issues/97306

* Some people ask for ways to reduce on-screen clutter because it makes it easier to focus. There's not a media query for that (and if there was, privacy-conscious users would turn it off). https://github.com/rust-lang/rust/issues/59829

This feature is designed to avoid these problems. Resizing the sidebar especially helps, because it provides a way to hide the sidebar without adding a new top-level button (which would add clutter), and it provides a way to make rustdoc play nicer in complex, custom screen layouts.

## Guide and Reference-level explanation

On a desktop or laptop with a mouse, resize the sidebar by dragging its right edge.

On any browser, including mobile phones, the sticky top bar or side bar can be hidden from the Settings area (the button with the cog wheel, next to the search bar). When it's hidden, a convenient button will appear on the search bar's left.

## Drawbacks

This adds more JavaScript code to the render blocking area.

## Rationale and alternatives

The most obvious way to allow people to hide the sidebar would have been to let them "manually enter mobile mode." The upside is that it's a feature we already have. The downside is that it's actually really hard to come up with a terse description. Is it:

* A Setting that forces desktop viewers to always have the mobile-style top bar? If so, how do we label it? Should it be visible on mobile, and, if so, does it just not do anything?
* A persistent hide/show sidebar button, present on desktop, just like on mobile? That's clutter that I'd like to avoid.

## Prior art

* The new file browser in GitHub uses a similar divider with a mouse-over indicator
* mdBook and macOS Finder both allow you to resize the sidebar to nothing as a gesture to hide it
* https://www.nngroup.com/articles/drag-drop/

## Future possibilities

https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Table.20of.20contents proposes a new, second sidebar (a table of contents). How should it fit in with this feature? Should it be resizeable? Hideable? Can it be accessed on mobile?
2023-12-15 11:51:23 +01:00
Guillaume Gomez
9e1797baf1 Extend GUI tests for doc_cfg 2023-12-07 10:44:55 +01:00
Guillaume Gomez
42fcba7a67 Add tests for headings anchor and links in headings 2023-12-05 15:59:40 +01:00
Guillaume Gomez
13b2156c68 Update rustdoc headings tests 2023-12-05 15:59:40 +01:00
Guillaume Gomez
768a614380 Add GUI tests for comments highlighting in items declaration 2023-12-01 11:23:38 +01:00
Michael Howell
7230f6c5c5 rustdoc: div.where instead of fmt-newline class
This is about equally readable, a lot more terse, and stops
special-casing functions and methods.

```console
$ du -hs doc-old/ doc-new/
671M    doc-old/
670M    doc-new/
```
2023-11-30 10:43:40 -07:00
Michael Howell
c910a49b05 rustdoc: remove small from small-section-header
There's no such thing as a big section header, so I don't know why the
name was used.
2023-11-29 13:40:07 -07:00
Michael Howell
63c50712f4 rustdoc-search: add support for associated types 2023-11-19 18:54:36 -07:00
Guillaume Gomez
2e4a36bb53 Add GUI test to ensure that implementations on foreign types are in the expected order 2023-11-02 18:02:14 +01:00
Oli Scherer
4512f211ae Accept less invalid Rust in rustdoc 2023-10-31 13:58:03 +00:00
Michael Howell
46fdeb24fd rustdoc: make JS trait impls act more like HTML 2023-10-22 16:51:32 -07:00
Michael Howell
d8afa673cc rustdoc: remove as_ref from method sidebar test
I fixed this in the code, but forgot to fix it in the test.
2023-10-22 15:56:15 -07:00
Michael Howell
fa10e4d667 rustdoc: use JS to inline target type impl docs into alias
This is an attempt to balance three problems, each of which would
be violated by a simpler implementation:

- A type alias should show all the `impl` blocks for the target
  type, and vice versa, if they're applicable. If nothing was
  done, and rustdoc continues to match them up in HIR, this
  would not work.

- Copying the target type's docs into its aliases' HTML pages
  directly causes far too much redundant HTML text to be generated
  when a crate has large numbers of methods and large numbers
  of type aliases.

- Using JavaScript exclusively for type alias impl docs would
  be a functional regression, and could make some docs very hard
  to find for non-JS readers.

- Making sure that only applicable docs are show in the
  resulting page requires a type checkers. Do not reimplement
  the type checker in JavaScript.

So, to make it work, rustdoc stashes these type-alias-inlined docs
in a JSONP "database-lite". The file is generated in `write_shared.rs`,
included in a `<script>` tag added in `print_item.rs`, and `main.js`
takes care of patching the additional docs into the DOM.

The format of `trait.impl` and `type.impl` JS files are superficially
similar. Each line, except the JSONP wrapper itself, belongs to a crate,
and they are otherwise separate (rustdoc should be idempotent). The
"meat" of the file is HTML strings, so the frontend code is very simple.
Links are relative to the doc root, though, so the frontend needs to fix
that up, and inlined docs can reuse these files.

However, there are a few differences, caused by the sophisticated
features that type aliases have. Consider this crate graph:

```text
 ---------------------------------
 | crate A: struct Foo<T>        |
 |          type Bar = Foo<i32>  |
 |          impl X for Foo<i8>   |
 |          impl Y for Foo<i32>  |
 ---------------------------------
     |
 ----------------------------------
 | crate B: type Baz = A::Foo<i8> |
 |          type Xyy = A::Foo<i8> |
 |          impl Z for Xyy        |
 ----------------------------------
```

The type.impl/A/struct.Foo.js JS file has a structure kinda like this:

```js
JSONP({
"A": [["impl Y for Foo<i32>", "Y", "A::Bar"]],
"B": [["impl X for Foo<i8>", "X", "B::Baz", "B::Xyy"], ["impl Z for Xyy", "Z", "B::Baz"]],
});
```

When the type.impl file is loaded, only the current crate's docs are
actually used. The main reason to bundle them together is that there's
enough duplication in them for DEFLATE to remove the redundancy.

The contents of a crate are a list of impl blocks, themselves
represented as lists. The first item in the sublist is the HTML block,
the second item is the name of the trait (which goes in the sidebar),
and all others are the names of type aliases that successfully match.

This way:

- There's no need to generate these files for types that have no aliases
  in the current crate. If a dependent crate makes a type alias, it'll
  take care of generating its own docs.
- There's no need to reimplement parts of the type checker in
  JavaScript. The Rust backend does the checking, and includes its
  results in the file.
- Docs defined directly on the type alias are dropped directly in the
  HTML by `render_assoc_items`, and are accessible without JavaScript.
  The JSONP file will not list impl items that are known to be part
  of the main HTML file already.

[JSONP]: https://en.wikipedia.org/wiki/JSONP
2023-10-22 15:56:14 -07:00
Michael Howell
4dfd827133 Added a new item, need to bump this count 2023-10-22 15:55:44 -07:00
Michael Howell
ade7ecf909 rustdoc: rename /implementors to /impl.trait
This is shorter, avoids potential conflicts with a crate
named `implementors`[^1], and will be less confusing when JS
include files are added for type aliases.

[^1]: AFAIK, this couldn't actually cause any problems right now,
but it's simpler just to make it impossible than relying on never
having a file named `trait.Foo.js` in the crate data area.
2023-10-22 15:47:34 -07:00
Michael Howell
fd9f1a7148 rustdoc: fix resize trouble with mobile 2023-10-11 12:15:33 -07:00
Michael Howell
273a302ac8 rustdoc: enforce BODY_MIN constraint on sidebar resize 2023-10-11 10:26:38 -07:00
Michael Howell
0983438faa rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
bors
6d05c430d2 Auto merge of #115948 - notriddle:notriddle/logo-lockup, r=fmease
rustdoc: show crate name beside smaller logo

*Blocked on https://github.com/rust-lang/cargo/pull/12800*

## Summary

In this PR, the crate name and version are always shown in the sidebar, even in subpages, and the lateral navigation is always shown in the sidebar, even in modules.

Clicking the crate name does the same thing clicking the logo always did: take you to the crate root (the crate's home page, at least within Rustdoc).

The Rust logo is also no longer shown by default for non-Rust docs.

### Screenshots

<details><summary>Before</summary>

| | Macro | Module |
|--|-------|--------|
| In crate | ![image](https://github.com/rust-lang/rust/assets/1593513/d5db0a46-2bb6-44a2-a3aa-2d915ecb8595) |![image](https://github.com/rust-lang/rust/assets/1593513/61f8c1ee-c298-4e2c-b791-18ecb79ab83b)
| In module[^1] | ![image](https://github.com/rust-lang/rust/assets/1593513/73abca59-0b69-4650-a1e2-7278ca34795c) | ![image](https://github.com/rust-lang/rust/assets/1593513/0baf02c2-2ec7-4674-80e5-a6a74a973376)

[^1]: This PR also includes a bug fix for derive macros not showing up in the lateral navigation part of the sidebar

</details>

#### Whole sidebar screenshots

| | Macro | Module |
|--|-------|--------|
| In crate | ![image](https://github.com/rust-lang/rust/assets/1593513/75d1bd07-41f7-4f11-ba24-fd5476e0586a) | ![image](https://github.com/rust-lang/rust/assets/1593513/52960259-2b65-4131-b380-01826f0a0eb7)
| In module | ![image](https://github.com/rust-lang/rust/assets/1593513/06e57928-8cb0-41bd-b152-be16cc53e5ec) | ![image](https://github.com/rust-lang/rust/assets/1593513/37291c69-2a07-4467-a382-d9b029084a47)

#### Different logo configurations

|         | Short crate name | Long crate name |
|---------|------------------|-----------------|
| Root    | ![short-root]    | ![long-root]
| Subpage | ![short-subpage] | ![long-subpage]

[short-root]: https://github.com/rust-lang/rust/assets/1593513/9e2b4fa8-f581-4106-b562-1e0372c13f79
[short-subpage]: https://github.com/rust-lang/rust/assets/1593513/8331cdb8-fa13-4671-a1e2-dcc1cdca7451
[long-root]: https://github.com/rust-lang/rust/assets/1593513/7d377fec-0f1d-4343-9f82-0e35a8f58056
[long-subpage]: https://github.com/rust-lang/rust/assets/1593513/3b3094a4-63c9-477c-8c15-b6075837df30

##### Without a logo

![image](https://github.com/rust-lang/rust/assets/1593513/66672b79-6c59-4be8-a527-25ef6f0b04ab)

### Preview pages

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/rocket/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/rocket_sync_db_pools/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rust-compiler/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rust/std/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/tokio/index.html

## Motivation

This improves visual information density (the construct with the logo and crate name is *shorter* than the logo on its own, because it's not square) and navigation clarity (we can now see what clicking the Rust logo does, specifically).

Compare this with the layout at [Phoenix's Hexdocs] (which is what this proposal is closely based on), the old proposal on [Internals Discourse] (which always says "Rust standard library" in the sidebar, but doesn't do the side-by-side layout).

[Phoenix's Hexdocs]: https://hexdocs.pm/phoenix/1.7.7/overview.html
[Internals Discourse]: https://internals.rust-lang.org/t/poc-of-a-new-design-for-the-generated-rustdoc/11018

## Guide-level explanation

This PR cleans up some of the sidebar navigation.

It makes the logo in the desktop sidebar a bit smaller, and puts the crate name and version next to it (either beside it, or below it, depending on if there's space), making it clearer what clicking on it does: click the crate name to open the crate's home page. It also removes the Rust logo from non-official-Rust crates, again to make the navigation and supply chain clearer (since the crate name has been added, the logo is no longer necessary for navigation).

It adds a bit more clarifying information for lateral navigation. On items that don't add their own sidebar items, it just shows its siblings directly below the crate name and logo, but for other items, it shows "In crate alloc" instead of just "In alloc". It also shows the lateral navigation tools on module pages, making modules consistent with every other item.

## Drawbacks

While this actually takes up less screen real estate than the old layout on desktop, it takes up more HTML. It's also a bit more visually complex.

## Rationale and alternatives

I could do what the Internals POC did and keep the vertically stacked layout all the time, instead of doing a horizontal stack where possible. It would take up more screen real estate, though.

## Prior art

This design is lifted almost verbatim from Hexdocs. It seems to work for them. [`opentelemetry_process_propagator`], for example, has a long application name.

[`opentelemetry_process_propagator`]: https://hexdocs.pm/opentelemetry_process_propagator/OpentelemetryProcessPropagator.html

## Unresolved questions

Maybe we should encourage crate authors to include their own logo more often? It certainly helps give people a better sense of "place." This seems to be blocked on coming up with an API to do it without requiring them to host the file somewhere.

## Future possibilities

Beyond this, plenty of other changes could be made to improve the layout, like

* Fix things so that clicking an item in the sidebar doesn't cause it to scroll back to the top.
  * The [Internals demo](https://utherii.github.io/new.html) does this right: clicking an item in the sidebar changes the content area, but the sidebar itself does not change. This is nice, because clicking is cheap and I can skim the opening few paragraphs while browsing.
  * The layout of the docs sidebar causes trouble to implement this, because it's different on different pages, but at least fix this on the file browser.
* Come up with a less cluttered way to do disclosure. There's a lot of `[-]` on the page.
  * We don't lack ideas to fix this one. We have *too many*.
* Do a better job of separating local navigation (vec::Vec links to vec::IntoIter) and the table of contents (vec::Vec links to vec::Vec::new).
  * A possibility: add a Back arrow next to the "In [module]" header?
    ![image](https://github.com/rust-lang/rust/assets/1593513/e969faf7-7722-457a-b8c6-8d962e9e1e23)
* Give readers more control of how much rustdoc shows them, and giving doc authors more control of how much it generates. Basically, https://github.com/rust-lang/rust/pull/115660 is great, let's do it too.

But those are mostly orthogonal, not future possibilities unlocked by this change.
2023-10-11 06:28:36 +00:00
Guillaume Gomez
4be9cfabf2
Rollup merge of #109422 - notriddle:notriddle/impl-disambiguate-search, r=GuillaumeGomez
rustdoc-search: add impl disambiguator to duplicate assoc items

Preview (to see the difference, click the link and pay attention to the specific function that comes up):

| Before | After |
|--|--|
| [`simd<i64>, simd<i64> -> simd<i64>`](https://doc.rust-lang.org/nightly/std/?search=simd%3Ci64%3E%2C%20simd%3Ci64%3E%20-%3E%20simd%3Ci64%3E) | [`simd<i64>, simd<i64> -> simd<i64>`](https://notriddle.com/rustdoc-demo-html-3/impl-disambiguate-search/std/index.html?search=simd%3Ci64%3E%2C%20simd%3Ci64%3E%20-%3E%20simd%3Ci64%3E) |
| [`cow, vec -> bool`](https://doc.rust-lang.org/nightly/std/?search=cow%2C%20vec%20-%3E%20bool) | [`cow, vec -> bool`](https://notriddle.com/rustdoc-demo-html-3/impl-disambiguate-search/std/index.html?search=cow%2C%20vec%20-%3E%20bool)

Helps with #90929

This changes the search results, specifically, when there's more than one impl with an associated item with the same name. For example, the search queries `simd<i8> -> simd<i8>` and `simd<i64> -> simd<i64>` don't link to the same function, but most of the functions have the same names.

This change should probably be FCP-ed, especially since it adds a new anchor link format for `main.js` to handle, so that URLs like `struct.Vec.html#impl-AsMut<[T]>-for-Vec<T,+A>/method.as_mut` redirect to `struct.Vec.html#method.as_mut-2`. It's a strange design, but there are a few reasons for it:

* I'd like to avoid making the HTML bigger. Obviously, fixing this bug is going to add at least a little more data to the search index, but adding more HTML penalises viewers for the benefit of searchers.

* Breaking `struct.Vec.html#method.len` would also be a disappointment.

On the other hand:

* The path-style anchors might be less prone to link rot than the numbered anchors. It's definitely less likely to have URLs that appear to "work", but silently point at the wrong thing.

* This commit arranges the path-style anchor to redirect to the numbered anchor. Nothing stops rustdoc from doing the opposite, making path-style anchors the default and redirecting the "legacy" numbered ones.

### The bug

On the "Before" links, this example search calls for `i64`:

![image](https://github.com/rust-lang/rust/assets/1593513/9431d89d-41dc-4f68-bbb1-3e2704a973d2)

But if I click any of the results, I get `f64` instead.

![image](https://github.com/rust-lang/rust/assets/1593513/6d89c692-1847-421a-84d9-22e359d9cf82)

The PR fixes this problem by adding enough information to the search result `href` to disambiguate methods with different types but the same name.

More detailed description of the problem at:
https://github.com/rust-lang/rust/pull/109422#issuecomment-1491089293

> When a struct/enum/union has multiple impls with different type parameters, it can have multiple methods that have the same name, but which are on different impls. Besides Simd, [Any](https://doc.rust-lang.org/nightly/std/any/trait.Any.html?search=any%3A%3Adowncast) also demonstrates this pattern. It has three methods named `downcast`, on three different impls.
>
> When that happens, it presents a challenge in linking to the method. Normally we link like `#method.foo`. When there are multiple `foo`, we number them like `#method.foo`, `#method.foo-1`, `#method.foo-2`, etc.
>
> It also presents a challenge for our search code. Currently we store all the variants in the index, but don’t have any way to generate unambiguous URLs in the results page, or to distinguish them in the SERP.
>
> To fix this, we need three things:
>
> 1. A fragment format that fully specifies the impl type parameters when needed to disambiguate (`#impl-SimdOrd-for-Simd<i64,+LANES>/method.simd_max`)
> 2. A search index that stores methods with enough information to disambiguate the impl they were on.
> 3. A search results interface that can display multiple methods on the same type with the same name, when appropriate OR a disambiguation landing section on item pages?
>
> For reviewers: it can be hard to see the new fragment format in action since it immediately gets rewritten to the numbered form.
2023-10-10 18:44:43 +02:00
Michael Howell
47c46324aa rustdoc: clean up the In [name] up-pointer
This commit makes three changes for consistency and readability:

  - It shows the sibling navigation on module pages. It's weird
    that it didn't work before, and is inconsistent with everything
    else (even Crates have sibling navigation with other Crates).
  - It hides the "In [parent]" header if it's the same as the
    current crate, and if there's no other header between them.
    We need to keep it on modules and types, since they have
    their own header and data between them, and we don't want
    to show siblings under a header implying that they're children.
  - It adds a margin to deal with the headers butting directly into
    the branding lockup.
2023-10-08 20:17:53 -07:00
Michael Howell
7c10c6f63d rustdoc: fix rustdoc-gui tests for logo changes 2023-10-08 20:17:53 -07:00
Michael Howell
28ee5da4b7 rustdoc: show crate name beside small logo
This commit changes the layout to something a bit less "look at my logo!!!111"
gigantic, and makes it clearer where clicking the logo will actually take you.
It also means the crate name is persistently at the top of the sidebar, even
when in a sub-item page, and clicking that name takes you back to the root.

|         | Short crate name | Long crate name |
|---------|------------------|-----------------|
| Root    | ![short-root]    | ![long-root]
| Subpage | ![short-subpage] | ![long-subpage]

[short-root]: https://github.com/rust-lang/rust/assets/1593513/fe2ce102-d4b8-44e6-9f7b-68636a907f56
[short-subpage]: https://github.com/rust-lang/rust/assets/1593513/29501663-56c0-4151-b7de-d2637e167125
[long-root]: https://github.com/rust-lang/rust/assets/1593513/f6a385c0-b4c5-4a9c-954b-21b38de4192f
[long-subpage]: https://github.com/rust-lang/rust/assets/1593513/97ec47b4-61bf-4ebe-b461-0d2187b8c6ca

https://notriddle.com/rustdoc-html-demo-4/logo-lockup/image/index.html

https://notriddle.com/rustdoc-html-demo-4/logo-lockup/crossbeam_channel/index.html

https://notriddle.com/rustdoc-html-demo-4/logo-lockup/adler/struct.Adler32.html

https://notriddle.com/rustdoc-html-demo-4/logo-lockup/crossbeam_channel/struct.Sender.html

This improves visual information density (the construct with the logo and
crate name is *shorter* than the logo on its own, because it's not
square) and navigation clarity (we can now see what clicking the Rust logo
does, specifically).

Compare this with the layout at [Phoenix's Hexdocs] (which is what this
proposal is closely based on), the old proposal on [Internals Discourse]
(which always says "Rust standard library" in the sidebar, but doesn't do the
side-by-side layout).

[Phoenix's Hexdocs]: https://hexdocs.pm/phoenix/1.7.7/overview.html
[Internals Discourse]: https://internals.rust-lang.org/t/poc-of-a-new-design-for-the-generated-rustdoc/11018

In newer versions of rustdoc, the crate name and version are always shown in
the sidebar, even in subpages. Clicking the crate name does the same thing
clicking the logo always did: return you to the crate root.

While this actually takes up less screen real estate than the old layout on
desktop, it takes up more HTML. It's also a bit more visually complex.

I could do what the Internals POC did and keep the vertically stacked layout
all the time, instead of doing a horizontal stack where possible. It would
take up more screen real estate, though.

This design is lifted almost verbatim from Hexdocs. It seems to work for them.
[`opentelemetry_process_propagator`], for example, has a long application name.

[`opentelemetry_process_propagator`]: https://hexdocs.pm/opentelemetry_process_propagator/OpentelemetryProcessPropagator.html

Has anyone written the rationale on why the Rust logo shows up on projects that
aren't the standard library? If we turned it off on non-standard crates by
default, it would line wrap crate names a lot less often.

Or maybe we should encourage crate authors to include their own logo more
often? It certainly helps give people a better sense of "place."

I'm not sure of anything that directly follows up this one. Plenty of other
changes could be made to improve the layout, like

* coming up with a less cluttered way to do disclosure (there's a lot of `[-]`
  on the page)
* doing a better job of separating lateral navigation (vec::Vec links to
  vec::IntoIter) and the table of contents (vec::Vec links to vec::Vec::new)
* giving readers more control of how much rustdoc hows them, and giving doc
  authors more control of how much it generates
* better search that reduces the need to browse

But those are mostly orthogonal, not future possibilities unlocked by this change.
2023-10-08 20:17:40 -07:00
Guillaume Gomez
2d25a25e5d Migrate GUI colors test to original CSS color format 2023-09-23 20:03:03 +02:00
Michael Howell
2a4c9d0756 Update search-result-impl-disambiguation.goml 2023-09-21 15:16:44 -07:00
Michael Howell
20b93b951a rustdoc: wait for section to open before trying to highlight
This fixes a problem where hash rewriting doesn't work with
`:target` CSS rules.
2023-09-21 15:16:44 -07:00
Michael Howell
3fbfe2bca5 rustdoc-search: add impl disambiguator to duplicate assoc items
Helps with #90929

This changes the search results, specifically, when there's more than
one impl with an associated item with the same name. For example,
the search queries `simd<i8> -> simd<i8>` and `simd<i64> -> simd<i64>`
don't link to the same function, but most of the functions have the
same names.

This change should probably be FCP-ed, especially since it adds a new
anchor link format for `main.js` to handle, so that URLs like
`struct.Vec.html#impl-AsMut<[T]>-for-Vec<T,+A>/method.as_mut` redirect
to `struct.Vec.html#method.as_mut-2`. It's a strange design, but there
are a few reasons for it:

* I'd like to avoid making the HTML bigger. Obviously, fixing this bug
  is going to add at least a little more data to the search index, but
  adding more HTML penalises viewers for the benefit of searchers.

* Breaking `struct.Vec.html#method.len` would also be a disappointment.

On the other hand:

* The path-style anchors might be less prone to link rot than the numbered
  anchors. It's definitely less likely to have URLs that appear to "work",
  but silently point at the wrong thing.

* This commit arranges the path-style anchor to redirect to the numbered
  anchor. Nothing stops rustdoc from doing the opposite, making path-style
  anchors the default and redirecting the "legacy" numbered ones.
2023-09-21 15:16:44 -07:00
Michael Howell
9fbee7dcc5 rustdoc: add test cases, and fix, search tabs 2023-09-19 21:46:06 -07:00
Guillaume Gomez
3f68468bc6
Rollup merge of #112725 - notriddle:notriddle/advanced-search, r=GuillaumeGomez
rustdoc-search: add support for type parameters

r? `@GuillaumeGomez`

## Preview

* https://notriddle.com/rustdoc-html-demo-4/advanced-search/rustdoc/read-documentation/search.html
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=option%3Coption%3CT%3E%3E%20-%3E%20option%3CT%3E
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=option%3CT%3E,%20E%20-%3E%20result%3CT,%20E%3E
* https://notriddle.com/rustdoc-html-demo-4/advanced-search/std/index.html?search=-%3E%20option%3CT%3E

## Description

When writing a type-driven search query in rustdoc, specifically one with more than one query element, non-existent types become generic parameters instead of auto-correcting (which is currently only done for single-element queries) or giving no result. You can also force a generic type parameter by writing `generic:T` (and can force it to not use a generic type parameter with something like `struct:T` or whatever, though if this happens it means the thing you're looking for doesn't exist and will give you no results).

There is no syntax provided for specifying type constraints for generic type parameters.

When you have a generic type parameter in a search query, it will only match up with generic type parameters in the actual function, not concrete types that match, not concrete types that implement a trait. It also strictly matches based on when they're the same or different, so `option<T>, option<U> -> option<U>` matches `Option::and`, but not `Option::or`. Similarly, `option<T>, option<T> -> option<T>` matches `Option::or`, but not `Option::and`.

## Motivation

This feature is motivated by the many "combinitor"-type functions found in generic libraries, such as Option, Future, Iterator, and Entry. These highly-generic functions have names that are almost completely arbitrary, and a type signature that tells you what it actually does.

This PR is a major step towards[^closure] being able to easily search for generic functions by their type signature instead of by name. Some examples of combinators that can be found using this PR (try them out in the preview):

* `option<option<T>> -> option<T>` returns Option::flatten
* `option<T> -> result<T>` returns Option::ok_or
* `option<result<T>> -> result<option<T>>` returns Option::transpose
* `entry<K, V>, FnOnce -> V` returns `Entry::or_insert_with` (and `or_insert_with_key`, since there's no way to specify the generics on FnOnce)

[^closure]:

    For this feature to be as useful as it ought to be, you should be able to search for *trait-associated types* and *closures*. This PR does not implement either of these: they are **Future possibilities**.

    Trait-associated types would allow queries like `option<T> -> iterator<item=T>` to return `Option::iter`. We should also allow `option<T> -> iterator<T>` to match the associated type version.

    Closures would make a good way to query for things like `Option::map`. Closure support needs associated types to be represented in the search index, since `FnOnce() -> i32` desugars to `FnOnce<Output=i32, ()>`, so associated trait types should be implemented first. Also, we'd want to expose an easy way to query closures without specifying which of the three traits you want.
2023-09-19 11:35:49 +02:00
Guillaume Gomez
e691752210 Migrate GUI colors test to original CSS color format 2023-09-16 11:54:25 +02:00
Michael Howell
cbccf800b8 rusdoc: add gui test for custom CSS themes
Based on
https://github.com/rust-lang/rust/pull/115829#issuecomment-1720056602
2023-09-14 13:24:23 -07:00
Guillaume Gomez
344ac25cbd Migrate GUI colors test to original CSS color format 2023-09-10 14:10:10 +02:00
Guillaume Gomez
a0aa59c934 Migrate GUI colors test to original CSS color format 2023-09-09 11:20:03 +02:00
Michael Howell
f42f357a73 rustdoc: update tests for generic parsing and correction 2023-09-03 13:06:08 -07:00
Michael Howell
0b3c617ec0 rustdoc-search: add support for type parameters
When writing a type-driven search query in rustdoc, specifically one
with more than one query element, non-existent types become generic
parameters instead of auto-correcting (which is currently only done
for single-element queries) or giving no result. You can also force a
generic type parameter by writing `generic:T` (and can force it to not
use a generic type parameter with something like `struct:T` or whatever,
though if this happens it means the thing you're looking for doesn't
exist and will give you no results).

There is no syntax provided for specifying type constraints
for generic type parameters.

When you have a generic type parameter in a search query, it will only
match up with generic type parameters in the actual function, not
concrete types that match, not concrete types that implement a trait.
It also strictly matches based on when they're the same or different,
so `option<T>, option<U> -> option<U>` matches `Option::and`, but not
`Option::or`. Similarly, `option<T>, option<T> -> option<T>`` matches
`Option::or`, but not `Option::and`.
2023-09-03 13:06:06 -07:00
Guillaume Gomez
8e5dff1d38 Migrate GUI colors test to original CSS color format 2023-09-03 12:49:22 +02:00