rust/tests/rustdoc-gui
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
..
src Rollup merge of #115660 - notriddle:notriddle/sidebar-resize, r=GuillaumeGomez 2023-12-15 11:51:23 +01:00
anchor-navigable.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
anchors.goml rustdoc: fix rustdoc-gui tests for logo changes 2023-10-08 20:17:53 -07:00
basic-code.goml rustdoc: use src consistently over source in code 2023-07-14 16:38:01 -07:00
check_info_sign_position.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
check-code-blocks-margin.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
check-stab-in-docblock.goml Migrate to 0.16.0 browser-ui-test version 2023-05-11 11:34:22 +02:00
code-blocks-overflow.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
code-color.goml Migrate GUI colors test to original CSS color format 2023-09-03 12:49:22 +02:00
code-sidebar-toggle.goml rustdoc: use src consistently over source in code 2023-07-14 16:38:01 -07:00
code-tags.goml rustdoc: rename /implementors to /impl.trait 2023-10-22 15:47:34 -07:00
codeblock-sub.goml Migrate to 0.16.0 browser-ui-test version 2023-05-11 11:34:22 +02:00
codeblock-tooltip.goml rustdoc: add interaction delays for tooltip popovers 2023-05-23 15:56:40 -07:00
cursor.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
default-settings.goml Migrate GUI colors test to original CSS color format 2023-09-23 20:03:03 +02:00
docblock-big-code-mobile.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
docblock-code-block-line-number.goml Migrate GUI colors test to original CSS color format 2023-06-25 10:49:28 +02:00
docblock-details.goml Convert some GUI tests color checks to use original format 2023-05-11 11:49:16 +02:00
docblock-table-overflow.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
docblock-table.goml Migrate GUI colors test to original CSS color format 2023-08-20 14:44:36 +02:00
duplicate-macro-reexport.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
enum-variants.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
escape-key.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
extend-css.goml Add/update tests for --extend-css option 2023-04-12 20:07:10 +02:00
fields.goml Add test to prevent regression for fields display 2023-06-21 17:42:53 +02:00
font-weight.goml rustdoc: remove small from small-section-header 2023-11-29 13:40:07 -07:00
go-to-collapsed-elem.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
hash-item-expansion.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
headers-color.goml rustdoc: remove small from small-section-header 2023-11-29 13:40:07 -07:00
headings.goml Migrate GUI colors test to original CSS color format 2023-07-15 15:14:06 +02:00
help-page.goml Migrate GUI colors test to original CSS color format 2023-09-09 11:20:03 +02:00
hide-mobile-topbar.goml rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
highlight-colors.goml Migrate GUI colors test to original CSS color format 2023-05-25 14:32:00 +02:00
huge-collection-of-constants.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
huge-logo.goml rustdoc: show crate name beside small logo 2023-10-08 20:17:40 -07:00
impl_on_foreign_order.goml Add GUI test to ensure that implementations on foreign types are in the expected order 2023-11-02 18:02:14 +01:00
impl-default-expansion.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
impl-doc.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
implementors.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
item-decl-colors.goml rustdoc: rename /implementors to /impl.trait 2023-10-22 15:47:34 -07:00
item-decl-comment-highlighting.goml Add GUI tests for comments highlighting in items declaration 2023-12-01 11:23:38 +01:00
item-info-alignment.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
item-info-overflow.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
item-info.goml Extend GUI tests for doc_cfg 2023-12-07 10:44:55 +01:00
item-summary-table.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
javascript-disabled.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
jump-to-def-background.goml rustdoc: use src consistently over source in code 2023-07-14 16:38:01 -07:00
label-next-to-symbol.goml Migrate GUI colors test to original CSS color format 2023-07-23 13:05:40 +02:00
links-color.goml rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
list_code_block.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
method-margins.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
mobile.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
module-items-font.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
no-docblock.goml rustdoc: rename /implementors to /impl.trait 2023-10-22 15:47:34 -07:00
notable-trait.goml Migrate GUI colors test to original CSS color format 2023-07-02 11:15:23 +02:00
overflow-tooltip-information.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
pocket-menu.goml Migrate GUI colors test to original CSS color format 2023-08-02 00:44:41 +02:00
README.md Change src/test to tests in source files, fix tidy and tests 2023-01-11 09:32:13 +00:00
run-on-hover.goml Migrate GUI colors test to original CSS color format 2023-08-04 19:45:32 +02:00
rust-logo.goml rustdoc: fix rustdoc-gui tests for logo changes 2023-10-08 20:17:53 -07:00
scrape-examples-button-focus.goml Migrate to 0.16.0 browser-ui-test version 2023-05-11 11:34:22 +02:00
scrape-examples-color.goml Rollup merge of #111844 - GuillaumeGomez:migrate-gui-test-color-4, r=notriddle 2023-05-23 00:32:20 +05:30
scrape-examples-fonts.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
scrape-examples-layout.goml Migrate to 0.16.0 browser-ui-test version 2023-05-11 11:34:22 +02:00
scrape-examples-toggle.goml Migrate GUI colors test to original CSS color format 2023-08-05 12:47:05 +02:00
search-corrections.goml rustdoc: update tests for generic parsing and correction 2023-09-03 13:06:08 -07:00
search-error.goml Migrate GUI colors test to original CSS color format 2023-08-06 12:46:35 +02:00
search-filter.goml Migrate GUI colors test to original CSS color format 2023-07-01 13:18:28 +02:00
search-form-elements.goml Migrate GUI colors test to original CSS color format 2023-08-19 17:52:20 +02:00
search-input-mobile.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
search-keyboard.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
search-no-result.goml Migrate GUI colors test to original CSS color format 2023-09-10 14:10:10 +02:00
search-reexport.goml Update rustdoc GUI tests 2023-07-18 14:34:24 +02:00
search-result-color.goml Migrate GUI colors test to original CSS color format 2023-09-16 11:54:25 +02:00
search-result-description.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
search-result-display.goml Improve search-result-display.goml test 2023-06-30 11:45:42 +02:00
search-result-go-to-first.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
search-result-impl-disambiguation.goml Update search-result-impl-disambiguation.goml 2023-09-21 15:16:44 -07:00
search-result-keyword.goml Move type name directly into the same DOM element 2023-06-03 16:37:43 +02:00
search-tab-change-title-fn-sig.goml Update rustdoc-gui test 2023-06-14 14:22:17 +02:00
search-tab.goml rustdoc-search: add support for associated types 2023-11-19 18:54:36 -07:00
setting-auto-hide-content-large-items.goml rustdoc: rename /implementors to /impl.trait 2023-10-22 15:47:34 -07:00
setting-auto-hide-item-methods-docs.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
setting-auto-hide-trait-implementations.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
setting-go-to-only-result.goml Add regression test for #112676 2023-06-16 20:41:00 +02:00
settings.goml Migrate GUI colors test to original CSS color format 2023-06-24 14:47:16 +02:00
shortcuts.goml Replace unicode value with character in shortcuts.goml test 2023-06-14 10:37:56 +02:00
sidebar-links-color.goml rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
sidebar-macro-reexport.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
sidebar-mobile-scroll.goml rustdoc: use CSS overscroll-behavior instead of JavaScript 2023-04-12 10:31:06 -07:00
sidebar-mobile.goml rustdoc: clean up the In [name] up-pointer 2023-10-08 20:17:53 -07:00
sidebar-resize-setting.goml rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
sidebar-resize-window.goml rustdoc: fix resize trouble with mobile 2023-10-11 12:15:33 -07:00
sidebar-resize.goml rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
sidebar-source-code-display.goml rustdoc: fix rustdoc-gui tests for logo changes 2023-10-08 20:17:53 -07:00
sidebar-source-code.goml Rollup merge of #115660 - notriddle:notriddle/sidebar-resize, r=GuillaumeGomez 2023-12-15 11:51:23 +01:00
sidebar.goml rustdoc: allow resizing the sidebar 2023-10-11 10:26:36 -07:00
source-anchor-scroll.goml rustdoc: fix rustdoc-gui tests for logo changes 2023-10-08 20:17:53 -07:00
source-code-page-code-scroll.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
source-code-page.goml rustdoc: fix rustdoc-gui tests for logo changes 2023-10-08 20:17:53 -07:00
src-font-size.goml rustdoc: use src consistently over source in code 2023-07-14 16:38:01 -07:00
stab-badge.goml Migrate GUI colors test to original CSS color format 2023-05-24 14:41:18 +02:00
struct-fields.goml Migrate to 0.16.0 browser-ui-test version 2023-05-11 11:34:22 +02:00
target.goml Migrate GUI colors test to original CSS color format 2023-05-29 16:03:56 +02:00
theme-change.goml rusdoc: add gui test for custom CSS themes 2023-09-14 13:24:23 -07:00
theme-defaults.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
theme-in-history.goml Migrate GUI colors test to original CSS color format 2023-05-31 13:03:46 +02:00
toggle-click-deadspace.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
toggle-docs-mobile.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
toggle-docs.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
toggle-implementors.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
toggled-open-implementations.goml Update rustdoc GUI tests to new browser-ui-test version 2023-04-11 19:14:35 +02:00
trait-sidebar-item-order.goml rustdoc: rename /implementors to /impl.trait 2023-10-22 15:47:34 -07:00
type-declation-overflow.goml rustdoc: rename /implementors to /impl.trait 2023-10-22 15:47:34 -07:00
type-impls.goml rustdoc: make JS trait impls act more like HTML 2023-10-22 16:51:32 -07:00
unsafe-fn.goml Migrate GUI colors test to original CSS color format 2023-08-15 14:46:54 +02:00
warning-block.goml Remove unneeded "background_color" parameter 2023-08-26 11:25:04 +02:00
where-whitespace.goml rustdoc: div.where instead of fmt-newline class 2023-11-30 10:43:40 -07:00

The tests present here are used to test the generated HTML from rustdoc. The goal is to prevent unsound/unexpected GUI changes.

This is using the browser-ui-test framework to do so. It works as follows:

It wraps puppeteer to send commands to a web browser in order to navigate and test what's being currently displayed in the web page.

You can find more information and its documentation in its repository.

If you need to have more information on the tests run, you can use --test-args:

$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --debug

If you don't want to run in headless mode (helpful to debug sometimes), you can use --no-headless:

$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --no-headless

To see the supported options, use --help.

Important to be noted: if the chromium instance crashes when you run it, you might need to use --no-sandbox to make it work:

$ ./x.py test tests/rustdoc-gui --stage 1 --test-args --no-sandbox