Some love for the rustbook (engine)

[azerupi]

So I have tried to improve the rustbook engine:

• The sidebar now looks a lot more like gitbook (I thinks it cleaner)
• Added the Open Sans font, in my opinion more readable for prolonged periods of time
• Changed the style for code blocks a little

I encountered 1 problem. In build.rs I added this google font url (I commented out the non-relevant parts for clarity)

let rustdoc_args: &[String] = &[
    //"".to_string(),
    //preprocessed_path.display().to_string(),
    //format!("-o{}", out_path.display()),
    //format!("--html-before-content={}", prelude.display()),
    //format!("--html-after-content={}", postlude.display()),
    //format!("--markdown-playground-url=http://play.rust-lang.org"),
    //format!("--markdown-css={}", item.path_to_root.join("rust-book.css").display()),
    format!("--markdown-css=http://fonts.googleapis.com/css?family=Open+Sans:400italic,700italic,400,700"),
    //"--markdown-no-toc".to_string(),
];

As you can see, I had to escape = with = because the string would get truncated if I didn't. Is that normal behaviour? Is that for security measures? If it is, isn't it a little weak if you can circumvent it by escaped characters? I don't know the reason behind, but I thought it was at least worth mentioning :)

Take your time for this PR, I still want to add multiple improvements:

• Like gitbook, possibility to change font by user
• Put css and js in their respective files (not hardcoded in rust)
• button to hide sidebar
• ...

So I'm not in a hurry to get this merged ;) But if you think it's good enough to be merged, go ahead. I will make another PR when I have other improvements.

In the image below is a screen of the improvements

[rust-highfive]

r? @nikomatsakis

(rust_highfive has picked a reviewer for you, use r? to override)

[azerupi]

r? @steveklabnik

[azerupi]

I want to add some icons.
At the moment I only need two. One to let the user modify the font and one to hide the sidebar. Is it ok if I add FontAwesome ?

But eventually, more could be used: search, github link, ...

They have a CDN so I don't need to include the icons in the rust repo, I can just link to their CDN (like I do for the Open Sans google font)

[steveklabnik]

it's important that docs render well when not-online, so I am tempted to say no to FontAwesome. There are some that already argue our existing fonts are too much...

[alexcrichton]

Nice improvements! A few thoughts:

• I agree with @steveklabnik, can we just stick to default fonts for now? We haven't had a great track record with custom fonts.
• Could you put up a copy online of the entire book to browse and compare?

[azerupi]

Oh that's a pity, it would have added a nice touch instead of menus made of words.

I don't see their point though, since everything is packed with the docs it doesn't matter much how much font's we use. The only argument I could understand is that it increases page load (but that's only relevant for the online version) and you can improve that by using CDN's + local fallback.

Is there another argument against it?

@alexcrichton I used Open Sans from google fonts so it's not added to the repo. It does show up when you browse locally and have a an internet connection. But if it doesn't load it's no problem at all because you fall back on the old font ;)

Could you put up a copy online of the entire book to browse and compare?

I think I can :) I will post a link when it's done

[azerupi]

@alexcrichton @steveklabnik here is the link: http://www.mathieudavid.org/test/rustbook/patch1/

I am working on a version to change font style at the moment I have included FontAwesome through CDN link I will add a local fallback to use words instead of icons when it doesn't load (for offline support). Once done I will put it online for you to review.
If then you still think that FontAwesome should not be included I will remove it and do only word menu :)

Update:
I have a really nice animation that hides the sidebar when a button is pressed. It needs a little bit more testing, but it seems to work correctly on all screen sizes.

For the variable font-sizes, it's a little trickier than I thought. I have to convert all the font-size to em instead of px. But that is defined in the shared css with rustdoc and I am too afraid to break things in the docs.. The ideal solution would be to separate the css for the book completely. This would also make it a tiny bit less dependant on rustdoc. And it would also make it possible to make multiple themes.

What do you think?

Update 2:
I put online what I already had, you can check it out here. It's not done yet, but it is fancy ;)

Just to be clear, this is not in the PR (yet)

[azerupi]

I would need some help with separating the css and js from rust. At the moment it is hardcoded in a Rust string and not very maintainable. But I'm not sure what I have to modify. I guess I will have to modify the make file to copy over those static assets to the "production" folder, but I have no clue how? edit: I found a way in the build.rs file from the rustbook.

Also it would be super convenient to add a make target like make trpl-static that would just copy the static files without rebuilding the rust code, for when you only modified the css or js.

[azerupi]

I have effectively isolated the css and js from the rust code. I put them in a static folder. Since css.rs wasn't used anymore I deleted it, was it used for something else?

It seems to behave correctly but I would feel a hell of a lot more confident if you guys could double check it ;)

Edit: This commit has a little downside: now when you change only the css or js, it doesn't rebuild because: nothing to be done so the static files aren't copied either.. How could I solve that?

[bors]

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

[azerupi]

@steveklabnik @alexcrichton any update on this? :)

[nhowell]

This line looks like junk leftover from a merge.

[azerupi]

Oh, yes my bad. I completely overlooked that. Correcting it right away :)

[nhowell]

For style, this line needs to be indented a level, I believe.

[nhowell]

This PR shouldn't be modifying this, right?

[azerupi]

I have no idea how this got modified, it probably got messed up when I merged the upstream branch to resolve the merge conflict. And I can't figure out how to revert it.. :(

[nhowell]

Okay. Yeah... that merge commit is pretty nasty looking. I wonder if a rebase and squash would take care of it (and then revert the changes to "src/llvm" and "src/rust-installer")

[azerupi]

I have never done that, could you walk me through the procedure?

[nhowell]

To rebase (I hope I have this correct):

$ git checkout doc-experiments
$ git fetch upstream
$ git rebase upstream/master

(Replace "upstream" with the name of your upstream remote if it's different.)

Let's see if that helps first. Squashing is a little more involved. (https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)

[azerupi]

Thank you ! It looks ok, I will check further and do a test build to see if everything is still good before I upload this time ;)

[nhowell]

And shouldn't be modifying this either, right?

[azerupi]

@nhowell The rebase worked, I think it's all good now. Thanks for your help !

[steveklabnik]

I think this change is overall good, but still am opposed to Yet More Web Fonts. We get a lot of complaints about our existing usage, I'd rather be conservative for now.

Other than that, r=me

[azerupi]

@steveklabnik Ok, I will remove the font then :) But I would like to explain why (in my opinion) it has only advantages. Could this maybe be discussed on the internal forum, to see what others think about it?

• It's not downloaded locally, meaning that it's not yet another dependency
• If this font fails to load (for example offline), the next font on the list is used, that is the current font. So it's not like it would fail to render.
• Open Sans is one of the most widely used fonts from google CDN, there is a very very big chance that the user already has it in his browser cache, so he probably doesn't even need to reload it (= improved page load)

And I think it's easier on the eye, but that's a matter of personal taste ;)

---

Was there a change with make trpl?
The behavior changed on my computer, now it rebuilds everything every time I run this command, taking hours.. :/

[steveklabnik]

I would like to explain why (in my opinion) it has only advantages.

A lot of people complain about our existing web font usage. I'd prefer to keep that usage level at about the same until we see if maybe someday we remove it entirely. We really need some help from some designer people :(

I don't know about any changes to make TRPL, but I bet an LLVM upgrade happened, which would trigger a full rebuild until after you've done it once. NO_REBUILD=1 sometimes helps with this, sometimes not...

[steveklabnik]

@bors: r+

[bors]

📌 Commit 003c3ea has been approved by steveklabnik

[bors]

💔 Test failed - auto-mac-64-opt

[steveklabnik]

Okay, I have no idea here. @alexcrichton @brson do either of you know why this would start failing?

[brson]

My guess is that this command to copy static assets from a relative directory of cwd is failing. Does this patch work with out-of-tree builds?

[brson]

Thanks for the rustbook love. It could be a swell tool.

[azerupi]

My guess is that this command to copy static assets from a relative directory of cwd is failing.

What would cause it to fail?

It works fine on my machine.. 😒

[brson]

It's creating a path from the current working directory to somewhere in the source directory. This should be fine if building from the source directory, but if building out of tree (running configure from somewhere other than the source directory) it will produce the wrong path. Again just a guess.

[azerupi]

That makes sense. Unfortunately I don't see any variable that points to the root directory and I cant use a relative path from src or tgt either because they are not fixed and are given as arguments.

Is there something I could use that will always point to the right directory?

[brson]

@azerupi I'd suggest following the example here and using include_bytes! to include these resources in the rustbook binary and then output them as needed at runtime.

[brson]

Sorry, didn't mean to close.

[bors]

⌛️ Testing commit 003c3ea with merge 358f1dd...

[Gankro]

@bors r-

Closing and Opening seemed to accidentally necro the build.

cc @barosl

[bors]

💔 Test failed - auto-mac-64-opt

[bors]

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

[Gankro]

@azerupi what's your status?

[azerupi]

what's your status?

Yes sorry for the wait, I have been distracted by other things (studies).
I will try to update the PR today with the needed modifications so it can finally be merged.

[azerupi]

I think it's good now, can someone review it?

[steveklabnik]

@bors: r+

[bors]

📌 Commit f6e9240 has been approved by steveklabnik

[steveklabnik]

Looks good, let's see what bors says :)

[bors]

⌛️ Testing commit f6e9240 with merge 75e4a78...

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt, auto-win-msvc-32-opt, auto-win-msvc-64-opt

[azerupi]

Great ! Finally, thanks to everyone for your patience :)