2022-01-21 19:41:47 +00:00
|
|
|
|
// Checks multiple things on the sidebar display (width of its elements, colors, etc).
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/test_docs/index.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
Simplify and unify rustdoc sidebar styles
This switches to just use size, weight, and spacing to distinguish
headings in the sidebar. We no longer use boxes, horizontal bars, or
centering to distinguish headings. This makes it much easier to
understand the hierarchy of headings, and reduces visual noise.
I also refactored how the mobile topbar works. Previously, we tried to
shift around elements from the sidebar to make the topbar. Now, the
topbar gets its own elements, which can be styled on their own. This
makes styling and reasoning about those elements simpler.
Because the heading font sizes are bigger, increase the sidebar width
slightly.
As a very minor change, removed version from the "All types" page. It's
now only on the crate page.
2022-01-07 00:48:24 +00:00
|
|
|
|
show-text: true
|
2022-12-27 20:59:00 +00:00
|
|
|
|
|
|
|
|
|
// First, check the sidebar colors.
|
|
|
|
|
define-function: (
|
|
|
|
|
"check-colors",
|
2024-04-01 19:11:22 +00:00
|
|
|
|
[theme, color, background_color],
|
2023-01-06 14:18:51 +00:00
|
|
|
|
block {
|
2023-04-11 17:11:34 +00:00
|
|
|
|
set-local-storage: {
|
2022-12-27 20:59:00 +00:00
|
|
|
|
"rustdoc-theme": |theme|,
|
|
|
|
|
"rustdoc-use-system-theme": "false",
|
2023-01-06 14:18:51 +00:00
|
|
|
|
}
|
|
|
|
|
reload:
|
2022-12-27 20:59:00 +00:00
|
|
|
|
// Checking results colors.
|
2023-01-06 14:18:51 +00:00
|
|
|
|
assert-css: (".sidebar", {
|
|
|
|
|
"color": |color|,
|
|
|
|
|
"background-color": |background_color|
|
|
|
|
|
}, ALL)
|
|
|
|
|
},
|
2022-12-27 20:59:00 +00:00
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
call-function: (
|
2023-01-06 14:18:51 +00:00
|
|
|
|
"check-colors",
|
|
|
|
|
{
|
|
|
|
|
"theme": "ayu",
|
2023-09-02 19:00:23 +00:00
|
|
|
|
"color": "#c5c5c5",
|
|
|
|
|
"background_color": "#14191f",
|
2023-01-06 14:18:51 +00:00
|
|
|
|
}
|
2022-12-27 20:59:00 +00:00
|
|
|
|
)
|
|
|
|
|
call-function: (
|
2023-01-06 14:18:51 +00:00
|
|
|
|
"check-colors",
|
|
|
|
|
{
|
|
|
|
|
"theme": "dark",
|
2023-09-02 19:00:23 +00:00
|
|
|
|
"color": "#ddd",
|
|
|
|
|
"background_color": "#505050",
|
2023-01-06 14:18:51 +00:00
|
|
|
|
}
|
2022-12-27 20:59:00 +00:00
|
|
|
|
)
|
|
|
|
|
call-function: (
|
2023-01-06 14:18:51 +00:00
|
|
|
|
"check-colors",
|
|
|
|
|
{
|
|
|
|
|
"theme": "light",
|
2023-09-02 19:00:23 +00:00
|
|
|
|
"color": "black",
|
|
|
|
|
"background_color": "#f5f5f5",
|
2023-01-06 14:18:51 +00:00
|
|
|
|
}
|
2022-12-27 20:59:00 +00:00
|
|
|
|
)
|
|
|
|
|
|
2023-04-11 17:11:34 +00:00
|
|
|
|
set-local-storage: {"rustdoc-theme": "light"}
|
Simplify and unify rustdoc sidebar styles
This switches to just use size, weight, and spacing to distinguish
headings in the sidebar. We no longer use boxes, horizontal bars, or
centering to distinguish headings. This makes it much easier to
understand the hierarchy of headings, and reduces visual noise.
I also refactored how the mobile topbar works. Previously, we tried to
shift around elements from the sidebar to make the topbar. Now, the
topbar gets its own elements, which can be styled on their own. This
makes styling and reasoning about those elements simpler.
Because the heading font sizes are bigger, increase the sidebar width
slightly.
As a very minor change, removed version from the "All types" page. It's
now only on the crate page.
2022-01-07 00:48:24 +00:00
|
|
|
|
// We reload the page so the local storage settings are being used.
|
|
|
|
|
reload:
|
|
|
|
|
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-text: (".sidebar > .sidebar-crate > h2 > a", "test_docs")
|
|
|
|
|
// Crate root has no "location" element
|
|
|
|
|
assert-count: (".sidebar .location", 0)
|
2022-10-18 18:14:01 +00:00
|
|
|
|
assert-count: (".sidebar h2", 1)
|
Simplify and unify rustdoc sidebar styles
This switches to just use size, weight, and spacing to distinguish
headings in the sidebar. We no longer use boxes, horizontal bars, or
centering to distinguish headings. This makes it much easier to
understand the hierarchy of headings, and reduces visual noise.
I also refactored how the mobile topbar works. Previously, we tried to
shift around elements from the sidebar to make the topbar. Now, the
topbar gets its own elements, which can be styled on their own. This
makes styling and reasoning about those elements simpler.
Because the heading font sizes are bigger, increase the sidebar width
slightly.
As a very minor change, removed version from the "All types" page. It's
now only on the crate page.
2022-01-07 00:48:24 +00:00
|
|
|
|
assert-text: ("#all-types", "All Items")
|
2023-09-02 19:00:23 +00:00
|
|
|
|
assert-css: ("#all-types", {"color": "#356da4"})
|
2021-05-02 16:59:31 +00:00
|
|
|
|
// We check that we have the crates list and that the "current" on is "test_docs".
|
2023-09-08 01:45:24 +00:00
|
|
|
|
assert-text: (".sidebar-elems ul.crate > li.current > a", "test_docs")
|
2021-05-02 16:59:31 +00:00
|
|
|
|
// And we're also supposed to have the list of items in the current module.
|
2022-05-05 19:56:40 +00:00
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(1)", "Re-exports")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(2)", "Modules")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(3)", "Macros")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(4)", "Structs")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(5)", "Enums")
|
2022-10-19 15:15:11 +00:00
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(6)", "Constants")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(7)", "Traits")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(8)", "Functions")
|
2023-08-21 23:20:00 +00:00
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(9)", "Type Aliases")
|
2022-10-19 15:15:11 +00:00
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(10)", "Unions")
|
|
|
|
|
assert-text: (".sidebar-elems section ul > li:nth-child(11)", "Keywords")
|
2023-02-08 02:00:18 +00:00
|
|
|
|
assert-text: ("#structs + .item-table .item-name > a", "Foo")
|
|
|
|
|
click: "#structs + .item-table .item-name > a"
|
2021-05-02 16:59:31 +00:00
|
|
|
|
|
|
|
|
|
// PAGE: struct.Foo.html
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-count: (".sidebar .sidebar-crate", 1)
|
2022-10-18 18:14:01 +00:00
|
|
|
|
assert-count: (".sidebar .location", 1)
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-count: (".sidebar h2", 3)
|
2021-05-31 09:51:22 +00:00
|
|
|
|
// We check that there is no crate listed outside of the top level.
|
|
|
|
|
assert-false: ".sidebar-elems > .crate"
|
2022-01-11 22:39:51 +00:00
|
|
|
|
|
2022-02-08 16:05:00 +00:00
|
|
|
|
click: ".sidebar-elems section .block li > a"
|
Simplify and unify rustdoc sidebar styles
This switches to just use size, weight, and spacing to distinguish
headings in the sidebar. We no longer use boxes, horizontal bars, or
centering to distinguish headings. This makes it much easier to
understand the hierarchy of headings, and reduces visual noise.
I also refactored how the mobile topbar works. Previously, we tried to
shift around elements from the sidebar to make the topbar. Now, the
topbar gets its own elements, which can be styled on their own. This
makes styling and reasoning about those elements simpler.
Because the heading font sizes are bigger, increase the sidebar width
slightly.
As a very minor change, removed version from the "All types" page. It's
now only on the crate page.
2022-01-07 00:48:24 +00:00
|
|
|
|
assert-property-false: ("html", {"scrollTop": "0"})
|
2022-01-11 22:39:51 +00:00
|
|
|
|
|
Simplify and unify rustdoc sidebar styles
This switches to just use size, weight, and spacing to distinguish
headings in the sidebar. We no longer use boxes, horizontal bars, or
centering to distinguish headings. This makes it much easier to
understand the hierarchy of headings, and reduces visual noise.
I also refactored how the mobile topbar works. Previously, we tried to
shift around elements from the sidebar to make the topbar. Now, the
topbar gets its own elements, which can be styled on their own. This
makes styling and reasoning about those elements simpler.
Because the heading font sizes are bigger, increase the sidebar width
slightly.
As a very minor change, removed version from the "All types" page. It's
now only on the crate page.
2022-01-07 00:48:24 +00:00
|
|
|
|
click: ".sidebar h2.location a"
|
2022-01-11 22:39:51 +00:00
|
|
|
|
assert-property: ("html", {"scrollTop": "0"})
|
|
|
|
|
|
2021-05-31 10:11:05 +00:00
|
|
|
|
// We now go back to the crate page to click on the "lib2" crate link.
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/test_docs/index.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
2023-09-02 19:00:23 +00:00
|
|
|
|
assert-css: (".sidebar-elems ul.crate > li:first-child > a", {"color": "#356da4"})
|
2022-10-10 18:37:19 +00:00
|
|
|
|
click: ".sidebar-elems ul.crate > li:first-child > a"
|
2021-05-02 16:59:31 +00:00
|
|
|
|
|
|
|
|
|
// PAGE: lib2/index.html
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/lib2/index.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
|
|
|
|
|
assert-count: (".sidebar .location", 0)
|
2021-05-02 16:59:31 +00:00
|
|
|
|
// We check that we have the crates list and that the "current" on is now "lib2".
|
2023-09-08 01:45:24 +00:00
|
|
|
|
assert-text: (".sidebar-elems ul.crate > li.current > a", "lib2")
|
2021-05-02 16:59:31 +00:00
|
|
|
|
// We now go to the "foobar" function page.
|
2022-10-10 18:37:19 +00:00
|
|
|
|
assert-text: (".sidebar-elems > section ul.block > li:nth-child(1)", "Modules")
|
|
|
|
|
assert-text: (".sidebar-elems > section ul.block > li:nth-child(2)", "Structs")
|
|
|
|
|
assert-text: (".sidebar-elems > section ul.block > li:nth-child(3)", "Traits")
|
|
|
|
|
assert-text: (".sidebar-elems > section ul.block > li:nth-child(4)", "Functions")
|
2023-08-21 23:20:00 +00:00
|
|
|
|
assert-text: (".sidebar-elems > section ul.block > li:nth-child(5)", "Type Aliases")
|
2023-02-08 02:00:18 +00:00
|
|
|
|
assert-text: ("#functions + .item-table .item-name > a", "foobar")
|
|
|
|
|
click: "#functions + .item-table .item-name > a"
|
2021-05-02 16:59:31 +00:00
|
|
|
|
|
|
|
|
|
// PAGE: fn.foobar.html
|
2022-10-18 18:14:01 +00:00
|
|
|
|
// In items containing no items (like functions or constants) and in modules, we have no
|
2023-09-23 19:59:58 +00:00
|
|
|
|
// "location" elements. Only the crate and optional parent module.
|
|
|
|
|
// This page, being directly below the crate, only has its heading.
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
|
2022-10-18 18:14:01 +00:00
|
|
|
|
assert-count: (".sidebar .location", 0)
|
2023-09-23 19:59:58 +00:00
|
|
|
|
assert-count: (".sidebar h2", 1)
|
2021-05-31 10:11:05 +00:00
|
|
|
|
// We check that we don't have the crate list.
|
|
|
|
|
assert-false: ".sidebar-elems > .crate"
|
|
|
|
|
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "./module/index.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
|
2021-06-19 10:56:55 +00:00
|
|
|
|
assert-text: (".sidebar > .location", "Module module")
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-count: (".sidebar .location", 1)
|
2023-09-23 19:59:58 +00:00
|
|
|
|
// Module page requires three headings:
|
|
|
|
|
// - Presistent crate branding (name and version)
|
|
|
|
|
// - Module name, followed by TOC for module headings
|
|
|
|
|
// - "In crate [name]" parent pointer, followed by sibling navigation
|
|
|
|
|
assert-count: (".sidebar h2", 3)
|
|
|
|
|
assert-text: (".sidebar > .sidebar-elems > h2", "In crate lib2")
|
|
|
|
|
assert-property: (".sidebar > .sidebar-elems > h2 > a", {
|
|
|
|
|
"href": "/lib2/index.html",
|
|
|
|
|
}, ENDS_WITH)
|
2021-05-31 09:51:22 +00:00
|
|
|
|
// We check that we don't have the crate list.
|
|
|
|
|
assert-false: ".sidebar-elems > .crate"
|
2021-05-02 16:59:31 +00:00
|
|
|
|
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "./sub_module/sub_sub_module/index.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-text: (".sidebar > .sidebar-crate > h2 > a", "lib2")
|
2021-06-19 10:56:55 +00:00
|
|
|
|
assert-text: (".sidebar > .location", "Module sub_sub_module")
|
2023-09-23 19:59:58 +00:00
|
|
|
|
assert-text: (".sidebar > .sidebar-elems > h2", "In lib2::module::sub_module")
|
|
|
|
|
assert-property: (".sidebar > .sidebar-elems > h2 > a", {
|
|
|
|
|
"href": "/module/sub_module/index.html",
|
|
|
|
|
}, ENDS_WITH)
|
2021-05-31 09:51:22 +00:00
|
|
|
|
// We check that we don't have the crate list.
|
2021-11-04 15:27:02 +00:00
|
|
|
|
assert-false: ".sidebar-elems .crate"
|
2022-02-08 16:05:00 +00:00
|
|
|
|
assert-text: (".sidebar-elems > section ul > li:nth-child(1)", "Functions")
|
2023-02-08 02:00:18 +00:00
|
|
|
|
assert-text: ("#functions + .item-table .item-name > a", "foo")
|
2022-01-25 04:19:09 +00:00
|
|
|
|
|
|
|
|
|
// Links to trait implementations in the sidebar should not wrap even if they are long.
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/lib2/struct.HasALongTraitWithParams.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
2022-02-08 16:05:00 +00:00
|
|
|
|
assert-property: (".sidebar-elems section .block li > a", {"offsetHeight": 29})
|
2022-02-04 06:50:32 +00:00
|
|
|
|
|
|
|
|
|
// Test that clicking on of the "In <module>" headings in the sidebar links to the
|
|
|
|
|
// appropriate anchor in index.html.
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/test_docs/struct.Foo.html"
|
2022-09-22 17:42:15 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
2022-10-10 18:37:19 +00:00
|
|
|
|
click: "//ul[@class='block mod']/preceding-sibling::h3/a"
|
2022-02-04 06:50:32 +00:00
|
|
|
|
// PAGE: index.html
|
2023-09-02 19:00:23 +00:00
|
|
|
|
assert-css: ("#modules", {"background-color": "#fdffd3"})
|
2022-09-22 17:42:15 +00:00
|
|
|
|
|
|
|
|
|
// Finally, assert that the `[+]/[−]` toggle doesn't affect sidebar width.
|
|
|
|
|
click: "#toggle-all-docs"
|
|
|
|
|
assert-text: ("#toggle-all-docs", "[+]")
|
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
|
|
|
|
click: "#toggle-all-docs"
|
|
|
|
|
assert-text: ("#toggle-all-docs", "[−]")
|
2023-01-08 20:29:57 +00:00
|
|
|
|
assert-property: (".sidebar", {"clientWidth": "200"})
|
2023-03-03 01:21:26 +00:00
|
|
|
|
|
|
|
|
|
// Checks that all.html and index.html have their sidebar link in the same place.
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/test_docs/index.html"
|
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-09-18 18:59:49 +00:00
|
|
|
|
store-property: (".sidebar .sidebar-crate h2 a", {
|
2023-05-10 08:56:59 +00:00
|
|
|
|
"clientWidth": index_sidebar_width,
|
|
|
|
|
"clientHeight": index_sidebar_height,
|
|
|
|
|
"offsetTop": index_sidebar_y,
|
|
|
|
|
"offsetLeft": index_sidebar_x,
|
|
|
|
|
})
|
2023-04-11 17:11:34 +00:00
|
|
|
|
go-to: "file://" + |DOC_PATH| + "/test_docs/all.html"
|
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-09-18 18:59:49 +00:00
|
|
|
|
assert-property: (".sidebar .sidebar-crate h2 a", {
|
2023-03-03 01:21:26 +00:00
|
|
|
|
"clientWidth": |index_sidebar_width|,
|
|
|
|
|
"clientHeight": |index_sidebar_height|,
|
2023-05-10 08:56:59 +00:00
|
|
|
|
"offsetTop": |index_sidebar_y|,
|
|
|
|
|
"offsetLeft": |index_sidebar_x|,
|
2023-03-03 01:21:26 +00:00
|
|
|
|
})
|