Tweaked Docs Design #12996

thehydroimpulse · 2014-03-18T09:05:04Z

Thoughts?

Signed-off-by: Daniel Fagnan <[email protected]>

huonw · 2014-03-18T09:33:44Z

Looks cool, although it would be useful if you could upload a rendered copy somewhere, so that we could browse through and get a broader sense of what it looks like.

(I wonder if "Type Definitions" would be better as "Type Aliases".)

Also, does this design become responsive easily? (Is being mobile friendly a goal we should have?)

thehydroimpulse · 2014-03-18T09:43:22Z

@huonw Cool. I'm currently uploading it to S3 for people to see/use.

Good question about being responsive.

The sidebar should collapse into a drop-down which would make the content the only focus on smaller screens.
Fonts should switch off of pixels to a more adaptable unit.
Code examples be toggle-able?

Code examples (not the short signature snippets) often doesn't work very well on a small screens.

I'll update the PR to make the search/header part more responsive.

brendanzab · 2014-03-18T10:10:20Z

The "experimental" thing is a little hidden. I was wondering... what about having tags next to items, saying experimental/deprecated (dunno if there are any others).

Here is an example from Mozilla Add-ons:

thehydroimpulse · 2014-03-18T10:54:36Z

@bjz Agreed.

adrientetar · 2014-03-18T11:52:26Z

I have the beginning of a responsive branch for the old impl here.

px is a relative unit to the device already, you can make it scalable with breakpoints (this is what Bootstrap does) but rems would allow a font-size relative to the html tag so that you just have to change it in one place.
I do still question the need for scaling font-size through.

EDIT: I see that you raised it. I'll look at it when it's online.

adrientetar · 2014-03-18T12:24:31Z

src/librustdoc/html/static/main.css

+    transition: border 500ms ease-out;
+    -webkit-transition: border 500ms ease-out;
+    -moz-transition: border 500ms ease-out;
+    -o-transition: border 500ms ease-out;


All major browsers support these attributes, we shouldn't be using vendor prefixes.

@adrientetar Ahh yes.

Signed-off-by: Daniel Fagnan <[email protected]>

thehydroimpulse · 2014-03-20T00:28:08Z

Fixed some issues, making the overall design a little bit more responsive.

(480px width, minimally useable size)

Demo: http://titan-rust.s3-website-us-east-1.amazonaws.com/doc/std/index.html

/cc @huonw @adrientetar

Also, I removed the search button because it doesn't do anything (from what I can tell), so it's quite useless.

emberian · 2014-03-20T00:40:01Z

The search button exists because otherwise people truly don't notice the search bar.

The non-blue hyperlinks are too light in my opinion. They're very hard to see:

It's even worse when I'm using redshift (flux-like).

thehydroimpulse · 2014-03-20T01:06:23Z

@cmr Agreed. I've made the link colors more visible.

Ahh, yeah. I see that about the search button.

adrientetar · 2014-03-20T12:23:47Z

src/librustdoc/html/static/main.css

@@ -155,12 +184,31 @@ nav.sub {

 .docblock h1, .docblock h2, .docblock h3, .docblock h4, .docblock h5 {


Where is this used? I can't seem to find the docblock class.

This is used for the H* within the docblock div which is in the #main.content block. Some pages might not have any of the headers, but many do.

huonw · 2014-03-20T12:30:52Z

For full responsivity, I think this will need to adjust the HTML to set the viewport width/default zoom (or whatever needs to happen); when I tested on my 480x800 phone (in vertical mode, i.e. width 480px) it still defaulted to being very zoomed out.

That said, it's probably fastest to navigate the docs when more of the page can be viewed at once; so I'm not 100% sure about our API docs making it hard to zoom out on a phone.

Of course the tutorial and guides should definitely be made as a usable as possible.

thehydroimpulse · 2014-03-20T14:18:51Z

@huonw Yeah, I'm testing that now. It's actually not that bad right now on mobile with the viewport width set correctly. The only major issues are font sizes being super inconsistent (thanks to the use of different units). The other issue is that the sidebar might not be best on mobile because of the limited width. Whenever the sidebar is displayed, the content has an even more limited width.

adrientetar · 2014-03-20T17:16:28Z

Viewport should be set via HTML.

adrientetar · 2014-03-20T18:10:52Z

@thehydroimpulse I am done reviewing. I have pushed a commit on top of your work, ada599255b5f6fd03d8c3a9e08374c1d61f7cbb7. It is only janitorial work, the design itself is unchanged.

Branch is adrientetar/rust/tree/docs_design.

thehydroimpulse · 2014-03-20T20:22:10Z

@adrientetar Ok awesome. I'll pull your changes.

Signed-off-by: Daniel Fagnan <[email protected]>

thehydroimpulse · 2014-03-21T00:05:06Z

Now all the fonts are using the simpler rem unit. Also adjusted the search section and made things a lot more responsive. I'm uploading the new changes to S3.

Signed-off-by: Daniel Fagnan <[email protected]>

thehydroimpulse · 2014-03-21T02:42:15Z

@adrientetar @cmr @huonw @bjz Updated S3 with the newest copy. The colors (like the green) might be a tad too bright, so let me know if that's the case.

Ideally, in the future, the sidebar can be compacted into a drop-down right before the search box. Then this can be used on mobile or smaller screens comfortably.

huonw · 2014-03-21T03:02:56Z

Nice. cc @brson.

(Could you double check that the tutorial, manual and the guides are still rendered correctly? If they've changed at all maybe you could upload one of them?)

thehydroimpulse · 2014-03-21T03:07:17Z

@huonw http://titan-rust.s3-website-us-east-1.amazonaws.com/doc/tutorial.html (All the other guides also work correctly and haven't changed.)

adrientetar · 2014-03-21T07:13:52Z

This does not affect tutorial and so on because they have a separate CSS file.

adrientetar · 2014-03-21T07:24:56Z

Generally speaking, I think that the flat design of before was better. A bit too rounded here in my opinion.

thehydroimpulse · 2014-03-21T07:33:26Z

@adrientetar I'm not really looking to implement anything "flat" per say, just stuff that makes sense and simple (although that makes it a flat design sometimes). I'd argue the current iteration has a much more polished look, especially with a more visible crate header, instead of a generic header with an underline.

adrientetar · 2014-03-21T07:33:41Z

src/librustdoc/html/layout.rs

@@ -51,7 +54,7 @@ pub fn render<T: fmt::Show, S: fmt::Show>(

    <section class=\"sidebar\">
        {logo, select, none{} other{
-            <a href='{root_path}{krate}/index.html'><img src='#' alt=''/></a>
+            <a href='{root_path}{krate}/index.html'><img src='#' alt='' width='100px' /></a>


Shouldn't have 'px', attribute is expected without unit here.

huonw · 2014-03-21T09:45:03Z

This does not affect tutorial and so on because they have a separate CSS file.

This is not just CSS changes.

(But, now I'm in a position to look at the code, it's obvious that they have no effect either.)

brson · 2014-03-22T00:06:28Z

Taking a look at this now.

brson · 2014-03-22T00:39:43Z

This looks like a solid improvement to me, and I especially like that it brings the style more inline with the rest of our docs.

Stylistically, I like the simplicity; I'm not crazy about the very rounded corners on headers.

Please do keep trying to unify all our different HTML styles.

If others' points are addressed then I'm happy to merge this.

thehydroimpulse · 2014-03-22T00:50:01Z

@brson Cool. Do you have any thoughts on the search button (i.e., should we keep it)? Yay or Nay? I can also make the corners slightly less rounded, if that makes things better.

brson · 2014-03-22T00:56:19Z

Let's leave the search button at least for now since others' want it. Do as you please with the corners. Thanks.

Signed-off-by: Daniel Fagnan <[email protected]>

thehydroimpulse · 2014-03-22T01:32:04Z

@brson Sounds good. I addressed the previous comments. If @adrientetar is done reviewing the code then I'll squash my commits.

adrientetar · 2014-03-22T06:39:59Z

Will look at it later today (if you can squash commits since my last one it would be cool)

adrientetar · 2014-03-23T08:06:33Z

src/librustdoc/html/static/main.css

@@ -155,20 +197,41 @@ nav.sub {

 .docblock h1, .docblock h2, .docblock h3, .docblock h4, .docblock h5 {
    margin-left: 0;
+    margin: 40px 0 10px 0;


Can you then cleanup the margin-left that is right before it?

alexcrichton · 2014-04-04T21:04:57Z

@thehydroimpulse ping? This looks like a nice redesign!

thehydroimpulse · 2014-04-06T02:56:41Z

@alexcrichton Gonna finish this up tomorrow.

thehydroimpulse · 2014-04-15T04:02:21Z

Closing this in favor of #13485

@brson

- Cherry-pick from #12996 - Use Fira Sans for headlines and sidebar (Light), Heuristica for the body (Adobe Utopia derivative). Both are licensed under the SIL OFL license. - A few tweaks Two examples: [modified `std`](http://adrientetar.legtux.org/cached/rust-docs/std.htm) and [modified `std::io`](http://adrientetar.legtux.org/cached/rust-docs/io.htm). cc #13484 **Blocked on rust-lang/prev.rust-lang.org#25 (for hosting of the fonts), that's showcased [here](http://adrientetar.github.io/rust-www/).** cc @brson, @thehydroimpulse

Tweaked the design to be a lot cleaner.

0cc392d

Signed-off-by: Daniel Fagnan <[email protected]>

adrientetar reviewed Mar 18, 2014
View reviewed changes

fixed issues

598b5af

Signed-off-by: Daniel Fagnan <[email protected]>

adrientetar reviewed Mar 20, 2014
View reviewed changes

doc: design changes cleanups

ada5992

thehydroimpulse added 2 commits March 20, 2014 15:39

made the overall design more responsive

fa25aaa

Signed-off-by: Daniel Fagnan <[email protected]>

made changes to the font sizes. Now using rems

abb6141

Signed-off-by: Daniel Fagnan <[email protected]>

adjusted font size. Stability badges.

8ebc240

Signed-off-by: Daniel Fagnan <[email protected]>

adrientetar reviewed Mar 21, 2014
View reviewed changes

fixed px in attribute

7f0aa11

Signed-off-by: Daniel Fagnan <[email protected]>

adrientetar reviewed Mar 23, 2014
View reviewed changes

adrientetar mentioned this pull request Apr 12, 2014

rustdoc: add webfonts and tweak the styles accordingly #13485

Merged

thehydroimpulse closed this Apr 15, 2014

chris-morgan mentioned this pull request Apr 26, 2014

Proposal: largely revert the recent docs style changes #13780

Closed

		@@ -155,12 +184,31 @@ nav.sub {

		.docblock h1, .docblock h2, .docblock h3, .docblock h4, .docblock h5 {

Tweaked Docs Design #12996

Tweaked Docs Design #12996

Conversation

thehydroimpulse commented Mar 18, 2014

huonw commented Mar 18, 2014

thehydroimpulse commented Mar 18, 2014

brendanzab commented Mar 18, 2014

thehydroimpulse commented Mar 18, 2014

adrientetar commented Mar 18, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thehydroimpulse commented Mar 20, 2014

emberian commented Mar 20, 2014

thehydroimpulse commented Mar 20, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huonw commented Mar 20, 2014

thehydroimpulse commented Mar 20, 2014

adrientetar commented Mar 20, 2014

adrientetar commented Mar 20, 2014

thehydroimpulse commented Mar 20, 2014

thehydroimpulse commented Mar 21, 2014

thehydroimpulse commented Mar 21, 2014

huonw commented Mar 21, 2014

thehydroimpulse commented Mar 21, 2014

adrientetar commented Mar 21, 2014

adrientetar commented Mar 21, 2014

thehydroimpulse commented Mar 21, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huonw commented Mar 21, 2014

brson commented Mar 22, 2014

brson commented Mar 22, 2014

thehydroimpulse commented Mar 22, 2014

brson commented Mar 22, 2014

thehydroimpulse commented Mar 22, 2014

adrientetar commented Mar 22, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexcrichton commented Apr 4, 2014

thehydroimpulse commented Apr 6, 2014

thehydroimpulse commented Apr 15, 2014