Add rustdoc settings menu

[GuillaumeGomez]

Fixes #18167.

r? @QuietMisdreavus

[rust-highfive]

Your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

Resolving deltas: 100% (614836/614836), completed with 4886 local objects.
---
[00:00:47] configure: rust.quiet-tests     := True
---
[00:05:20] tidy error: /checkout/src/librustdoc/html/static/settings.js: missing trailing newline
[00:05:21] some tidy checks failed
[00:05:21]
[00:05:21]
[00:05:21] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:05:21] expected success, got: exit code: 1
[00:05:21]
[00:05:21]
[00:05:21] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:05:21] Build completed unsuccessfully in 0:02:02
[00:05:21] make: *** [tidy] Error 1
[00:05:21] Makefile:79: recipe for target 'tidy' failed
---
$ find $HOME/Library/Logs/DiagnosticReports -type f -name '*.crash' -not -name '*.stage2-*.crash' -not -name 'com.apple.CoreSimulator.CoreSimulatorService-*.crash' -exec printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" {} \; -exec head -750 {} \; -exec echo travis_fold":"end:crashlog \; || true
find: `/home/travis/Library/Logs/DiagnosticReports': No such file or directory
travis_time:end:13ee506e:start=1523653444149841583,finish=1523653444156873560,duration=7031977
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:03961c93
$ dmesg | grep -i kill
[   10.902289] init: failsafe main process (1092) killed by TERM signal

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[GuillaumeGomez]

Ready it is!

[ollie27]

If settings.html is supposed to be a shared file then its contents should not depend on the crate that generated it so the output is deterministic when documenting multiple crates at the same time. Currently settings.html contains lines like:

<a href='./std_unicode/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a>

Perhaps it would be better for the settings to be in a drop-down menu like the themes instead of a separate file.

[QuietMisdreavus]

Alternately, if it's going to be in a separate page, is it possible to put it into librustdoc/html/static/ somehow? Or perhaps using a new template so that the sidebar doesn't link to anything crate-specific?

On the other hand, when i ran it myself, the link gets changed to javascript:void at page load time. The sidebar also gets filled with the crate list, so at least there's a means to get back to regular documentation.

[bors]

☔ The latest upstream changes (presumably #50033) made this pull request unmergeable. Please resolve the merge conflicts.

[ollie27]

Another option would be to use a pop-up like the help pop-up.

[GuillaumeGomez]

@ollie27: Check out the changes, I remove the url on the logo. :)

[GuillaumeGomez]

And I'd prefer to avoid adding even more JS than necessary. Settings is in its own page, with its own JS and everything is fine as is.

[ollie27]

The issue with removing the url with JS is that it doesn't help with bit-for-bit deterministic builds (#34902). Also the logo itself is crate specific, as is the favicon. How about not sharing settings.html and generating it once for each crate next to all.html?

[GuillaumeGomez]

Because that's repeated data. I don't really see the issue in here, if the favicon is switched because the user changed it in one crate, then so be it?

[QuietMisdreavus]

How about this: We can clone the Layout when generating the settings page, to remove the krate, and also tweak the layout to render the logo, but not the link, when there's a logo but no krate to link to. That way, the logo is present, the build is reproducible, and the settings page is still one file for the whole bundle.

[GuillaumeGomez]

@QuietMisdreavus: Sounds like a good solution, I'll go for it then.

[GuillaumeGomez]

@QuietMisdreavus: Done!

[ollie27]

As I've already said, the logo and favicon can also be different between crates. If you document two crates at the same time that have different logos, then which logo should the settings.html page use? I suggest setting the logo and favicon to an empty string here as well.

[ollie27]

This file should be generated each time to pick up changes to rustdoc options that can affect it.

[ollie27]

</div> is missing. Also the .to_owned() isn't needed.

[GuillaumeGomez]

Updated. Anything else you want me to change @ollie27 ?

[ollie27]

Other than that one unneeded change this looks good to me.

[ollie27]

This change is no longer needed now that the logo has been removed.

[GuillaumeGomez]

Done as well!

[GuillaumeGomez]

@bors: r=ollie27,QuietMisdreavus

[bors]

📌 Commit 1f7892f has been approved by ollie27,QuietMisdreavus

[bors]

⌛ Testing commit 1f7892f with merge 28193e8...

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: ollie27,QuietMisdreavus
Pushing 28193e8 to master...