300 Commits

Author	SHA1	Message	Date
Michael Howell	12dc24f460	rustdoc-search: simplify rules for generics and type params ... This commit is a response to feedback on the displayed type signatures results, by making generics act stricter. Generics are tightened by making order significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected. Find the discussion on: * <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149> * <https://github.com/rust-lang/rust/pull/124544#issuecomment-2204272265> * <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search/near/476841363>	2024-10-30 12:27:48 -07:00
Michael Howell	20a4b4fea1	rustdoc-search: show types signatures in results	2024-10-30 10:35:39 -07:00
Michael Howell	5c7e7dfe10	rustdoc-search: pass original names through AST	2024-10-30 10:35:38 -07:00
Guillaume Gomez	26b6ccdbd7	Add GUI regression test for variant structfields margins	2024-10-28 11:16:38 +01:00
Guillaume Gomez	c50bfda34f	Add GUI regression test for doc struct fields margins	2024-10-27 11:26:45 +01:00
Jubilee	b80593995d	Rollup merge of #132183 - GuillaumeGomez:code-in-docblock, r=notriddle ... Fix code HTML items making big blocks if too long Encountered this bug randomly where `code` item in docblocks would look like this:  With this fix it looks like this:  r? ``@notriddle``	2024-10-26 21:58:39 -07:00
Guillaume Gomez	88f4425dd2	Update GUI test	2024-10-26 20:40:59 +02:00
Guillaume Gomez	ae66380da0	Add GUI regression test for code in doc blocks	2024-10-26 15:45:17 +02:00
Michael Howell	a53655a023	rustdoc: adjust spacing and typography in header	2024-10-23 19:15:23 -04:00
Guillaume Gomez	5e6033ea8b	Strengthen some GUI tests	2024-10-09 21:23:20 +02:00
Guillaume Gomez	12d5f0aa2c	Add GUI regression test for methods left margin on mobile	2024-10-09 21:01:08 +02:00
Guillaume Gomez	16844e2485	Fix methods alignment on mobile	2024-10-09 21:01:08 +02:00
Jubilee	869b8eb7ee	Rollup merge of #131257 - GuillaumeGomez:fix-list-margins, r=notriddle ... [rustdoc] Fix list margins Fixes https://github.com/rust-lang/rust/issues/131106. Fixes #131223. Follow-up of #130933. This PR changes the display as follow: the margin between list items is reduced by half to ensure that they visually still seem part of the same list, while also being bigger than previously which improves display for list items with more than one paragragh. Paragraphs also get they bottom margin reduced to a little bit less than the list items bottom margin for two reasons: 1. The list items keep having the biggest bottom margin which makes it better for coherency. 2. The paragraphs are still visually separated but they don't "overcome" the list. | before | after | |-|-| |  |  | Can be tested [here](https://rustdoc.crud.net/imperio/fix-list-margins/doc/test_docs/long_list/index.html). r? ``@notriddle``	2024-10-04 14:11:38 -07:00
Guillaume Gomez	1c63ec9fa0	Add GUI regression test for #130622 and for #131223	2024-10-04 18:01:52 +02:00
Guillaume Gomez	32099dbc1e	Enable --no-sandbox option by default for rustdoc GUI tests	2024-10-04 12:11:23 +02:00
bors	0d6e130196	Auto merge of #131002 - steffahn:rustdoc-long-names-fix, r=notriddle ... In redesigned rustdoc toolbar: Adjust spacings and sizing to improve behavior with over-long names Fixes #130993. Some additional adjustments also fix more issues I’ve noticed such as: * on small screens, opening search made the 3 bottons move down very slightly (because the row with the crate picker got larger, enlarging the whole grid), this is fixed with a `min-height: 60px` on the toolbar * with long names in the “breadcrumps” area, wrapping was very broken *  * fixed: *  * the left grid area has a minimal width (105px); like before, that leaves about enough space for crate names becoming as short as “all cra…”; to save even more space, there’s support for a little bit of extra squeezing of the buttons *  *  *  I’m really not super good with HTML or CSS stuff at all; there seem to be many magical numbers already, I’ve just used `px` values until things look right, I hope that’s okay 🤷‍♂️ r? `@GuillaumeGomez` cc `@notriddle`	2024-09-29 22:04:32 +00:00
Michael Howell	c27b54ac4a	rustdoc-gui: fix test cases	2024-09-29 10:02:06 -07:00
Guillaume Gomez	2f16ff7b37	Make use of wait-for*-false commands	2024-09-28 18:04:00 +02:00
Michael Goulet	0a0ea28f26	Rollup merge of #129545 - notriddle:notriddle/toolbar-v2, r=GuillaumeGomez ... rustdoc: redesign toolbar and disclosure widgets Fixes #77899 Fixes #90310 ## Preview | before | after | ------ | ----- |  |  |  |  |  |  |  |  |  |  | N/A |  |  |  |  |  https://notriddle.com/rustdoc-html-demo-12/toolbar-v2/std/index.html ## Description 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. CC <https://github.com/rust-lang/rust/pull/113074#issuecomment-1677469680> and ``@jsha`` regarding the use of triangles for disclosure, which is what everyone wanted, but was pending a good toggle-all button. This PR adds a toggle-all button that should work. Settings and Help are also migrated, so that the whole group can benefit from being described using actual words. The breadcrumbs also get redesigned, so that they use less space, by shrinking the parent module path parts. This is done at the same time as the toolbar redesign because it's, effectively, moving space from the toolbar to the breadcrumbs. This is aimed at avoiding any line wrapping at desktop sizes. ## Prior art This style of toolbar, with explicit labels on the buttons, used to be more popular. It's not very common in web browsers nowadays, and for truly universal icons like ⬅️ I can understand why, but words are great when icons fail. 	2024-09-23 23:49:11 -04:00
Michael Howell	cc3ffe4c91	Tweak breadcrumbs list	2024-09-23 09:21:39 -07:00
Guillaume Gomez	f451a410e3	Add GUI regression test for non-rust code blocks line numbers	2024-09-22 00:18:44 +02:00
Guillaume Gomez	55058b6c74	Add GUI tests for line numbers padding	2024-09-20 16:02:32 +02:00
Guillaume Gomez	660210c4af	Add GUI test to check size of additional scraped examples	2024-09-20 16:02:32 +02:00
Michael Howell	df307d0085	rustdoc: tweak spacing in toolbar	2024-09-10 17:56:17 -07:00
Michael Howell	5b1b2e97e3	rustdoc: make the header show all three buttons ... This tweaks it to use less space for the breadcrumbs.	2024-09-10 17:56:06 -07:00
Michael Howell	d05323c7b4	rustdoc: redesign toolbar and disclosure widgets ... 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.	2024-09-10 17:56:05 -07:00
Matthias Krüger	9be97ae8e2	Rollup merge of #129796 - GuillaumeGomez:unify-code-examples, r=notriddle ... 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```	2024-09-05 18:58:56 +02:00
Matthias Krüger	e1da72c6e8	Rollup merge of #120736 - notriddle:notriddle/toc, r=t-rustdoc ... 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](06137bde8c/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.	2024-09-05 03:47:40 +02:00
Guillaume Gomez	7157f98cb4	Fix square corners on line numbers when code is collapsed	2024-09-03 22:17:04 +02:00
Guillaume Gomez	55bc638a1d	Fix wrong padding for expanded scraped example	2024-09-03 01:04:59 +02:00
Guillaume Gomez	e3af6dc239	Simplify CSS but wrapping scraped example into a div and move the title out of the code block	2024-09-02 15:59:00 +02:00
Matthias Krüger	c90991db17	Rollup merge of #127474 - tesuji:foldable-inline-derefs, r=t-rustdoc ... 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	2024-09-02 04:19:27 +02:00
Guillaume Gomez	01d8235ae1	Fix scraped examples background gradient	2024-09-02 00:02:03 +02:00
Guillaume Gomez	5a85632623	Correctly handle code examples buttons position	2024-09-01 23:43:27 +02:00
Guillaume Gomez	4825fb198f	Add missing CSS variables in GUI test for custom-theme.css	2024-09-01 20:49:41 +02:00
Guillaume Gomez	dd5f7bc628	Add GUI regression test for scraped examples title position on mobile	2024-09-01 20:49:41 +02:00
Guillaume Gomez	84259ff23b	Add GUI tests to ensure that rounded corners on code blocks are working as expected	2024-09-01 20:49:41 +02:00
Guillaume Gomez	5b75f8a892	Update rustdoc GUI tests	2024-08-31 00:12:16 +02:00
Michael Howell	bead042d5e	rustdoc: add test case for modnav position when TOC is off	2024-08-20 16:54:04 -07:00
Michael Howell	12a3c42ccc	rustdoc: consistentify #TOC and #ModNav to lowercase	2024-08-20 16:51:40 -07:00
Michael Howell	a7aea5d96b	Add configuration options to hide TOC or module navigation	2024-08-20 16:27:42 -07:00
Michael Howell	1aebff96ad	Add Top TOC support to rustdoc ... 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).	2024-08-20 16:27:42 -07:00
Michael Howell	9d7574f9b0	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, as a design that made rapid scanning easier while avoiding the inherent trade-offs in summarizing.	2024-08-19 18:14:35 -07:00
Guillaume Gomez	c6e3385d95	Rollup merge of #128394 - GuillaumeGomez:run-button, r=t-rustdoc ... Unify run button display with "copy code" button and with mdbook buttons Follow-up of https://github.com/rust-lang/rust/pull/128339. It looks like this (coherency++, yeay!):  Can be tested [here](https://rustdoc.crud.net/imperio/run-button/foo/struct.Bar.html). r? `@notriddle`	2024-08-12 17:09:15 +02:00
Michael Howell	3a183256ad	rustdoc-search: account for numeric disambiguators on impls ... Fixes #128676	2024-08-06 07:36:12 -07:00
Guillaume Gomez	59cb15946d	Prevent clicking on a link or on a button to toggle the code example buttons visibility	2024-08-05 11:05:40 +02:00
Guillaume Gomez	be71bd9cec	Update GUI tests for code example buttons	2024-08-05 11:04:51 +02:00
Matthias Krüger	c2b085b4d4	Rollup merge of #128339 - GuillaumeGomez:click-code-example, r=notriddle ... [rustdoc] Make the buttons remain when code example is clicked Follow-up of https://github.com/rust-lang/rust/pull/125779. One current issue we have with "run" button and the newly added copy code button is that if you're on mobile devices, you can't use them. I took a look at how `mdbook` is handling it and when you click on a code example, they show the buttons. I think it's a really good idea as if you want to copy the code on your mobile device, you will click on it, showing the buttons. Feature can be tested [here](https://rustdoc.crud.net/imperio/click-code-example/foo/struct.Bar.html). r? `@notriddle`	2024-07-30 04:31:55 +02:00
Guillaume Gomez	99906dc89c	Add rustdoc GUI test to check click on code examples	2024-07-29 21:14:36 +02:00
Michael Howell	3bf8bcfbe0	rustdoc: properly handle path wrapping	2024-07-29 10:31:02 -07:00