New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"The Rust Programming Language" #19461

Closed
wants to merge 3 commits into
base: master
from

Conversation

Projects
None yet
8 participants
@steveklabnik
Member

steveklabnik commented Dec 2, 2014

This is a preliminary PR that significantly changes Rust's documentation.

TL;DR: Remove the distinction between "the guide" and "the guides", and merge them into one big 'ol "The Rust Programming Language." You can see it rendered here: http://steveklabnik.github.io/the_rust_programming_language/

This uses https://github.com/aturon/rust-book to generate said final product.

Basically, the new "book" as I'm calling it looks like this:

Part I: Basics <- this is the first half of the current Guide. Linear.
Part II: Intermediate <- this is some of the current Guide, with the invididual Guides replacing chapters where relevant. Can be read in any order.
Part III: Adavanced <- the most advanced of the previous Guides. Can be read in any order.

Conceivably, this could even fix rust-lang/rust-by-example#278 by making Rust by example a part IV or something. While Rust By Example doesn't currently use Rustbook, it could.

I don't think the Makefile is currently up to snuff, but it works, at least. Ish. Feedback very welcome.

This also adds an optional dependency on rustbook, which may not be something that we want.

steveklabnik added some commits Dec 2, 2014

makefile stuff
this is probably too simple, but it'll work for now
@Gankro

This comment has been minimized.

Contributor

Gankro commented Dec 2, 2014

I haven't had a lot of love for Rustbook's stability and style as used on aturon's style guide. However your build seems considerably more stable, did you do anything different? Style things can of course be worked out.

Like the general direction, though. This is a much more coherent vision for our high-level documentation.

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Dec 2, 2014

@Gankro what do you mean by 'stable' in this context?

@Gankro

This comment has been minimized.

Contributor

Gankro commented Dec 2, 2014

http://aturon.github.io/ frequently flickers the content or will just not load it at all. Actually it just seems totally broken to me now. Possibly just bitrot? Has the official version been moved?

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Dec 2, 2014

Loads just fine here. Odd.

I just built it with my own compiled version. But as you say, style is fixable regardless.

Sent from my iPhone

On Dec 2, 2014, at 18:31, Alexis Beingessner notifications@github.com wrote:

http://aturon.github.io/ frequently flickers the content or will just not load it at all. Actually it just seems totally broken to me now. Possibly just bitrot? Has the official version been moved?


Reply to this email directly or view it on GitHub.

@MatejLach

This comment has been minimized.

Contributor

MatejLach commented Dec 2, 2014

Loads and looks fine on my end as well...

@Gankro

This comment has been minimized.

Contributor

Gankro commented Dec 2, 2014

Hmm, whenever I click on a menu item the page just goes white. I have to refresh to get it to actually render :/ (on aturon's not yours).

@MatejLach

This comment has been minimized.

Contributor

MatejLach commented Dec 2, 2014

This would be one of the problems, where one's results will wary greatly depending on what fonts, browser, packages they have/not have installed etc.
The discrepancy between various browsers and their many possible configurations it just a pain.
Case in point:
So for me both http://aturon.github.io and http://steveklabnik.github.io/the_rust_programming_language work fine (and exactly the same), so in this case I happen to have my browser/system configured "correctly", but in an unrelated case, I don't have fonts on rust-lang.org showing up correctly until I install the Fira Sans font, so clearly in that case, my browser is being configured "incorrectly".

sigh

@brson

This comment has been minimized.

Contributor

brson commented Dec 2, 2014

I'd like to take some time to think about how the build and automation around such a change will work before we merge.

The font problem with the docs in general is frustrating. Maybe we should get rid of Fira and use a more typical local font until the bug is figured out.

@LaoZhongGu

This comment has been minimized.

LaoZhongGu commented Dec 3, 2014

Great Job.

@adrientetar

This comment has been minimized.

Contributor

adrientetar commented Dec 3, 2014

I don't have fonts on rust-lang.org showing up correctly until I install the Fira Sans font, so clearly in that case, my browser is being configured "incorrectly".

AFAICT, it’s an Arch Linux-specific bug that has little to do with configuration.

@MatejLach

This comment has been minimized.

Contributor

MatejLach commented Dec 3, 2014

@adrientetar It may be, but it's similar in nature nonetheless. (the same thing showing up differently depending on your system)
However, since I have been consistently unable to reproduce it on ANY other website, it must be a very obscure bug that is only triggered by something at rust-lang.org

@adrientetar

This comment has been minimized.

Contributor

adrientetar commented Dec 3, 2014

I get Resource interpreted as Font but transferred with MIME type binary/octet-stream: "http://doc.rust-lang.org/Heuristica-Italic.woff". in the console when opening a rust page.

Not sure if it’s related but it looks like that needs fixing server-side: http://stackoverflow.com/questions/15521130/google-warning-resource-interpreted-as-font-but-transferred-with-mime-type-appl
cc @alexcrichton

@alexcrichton

This comment has been minimized.

Member

alexcrichton commented Dec 4, 2014

@adrientetar that is worrisome! Our instance of doc.rust-lang.org actually just proxies requests to S3, and it looks like when publishing docs to S3 (using s3cmd) there's no way to instruct it that these *.woff files have a particular content type (one way or another). You wouldn't happen to know how to add this header on-the-fly with nginx would you?

@adrientetar

This comment has been minimized.

Contributor

adrientetar commented Dec 4, 2014

I do not use nginx. Can you pass the MIME type manually with -m to s3cmd?

@mdinger

This comment has been minimized.

Contributor

mdinger commented Dec 4, 2014

@Gankro Could be corrupted browser profile. See rust-lang/rust-by-example#201 (comment) if it's an issue in firefox. Other browsers probably have cleaning instructions as well.

@MatejLach

This comment has been minimized.

Contributor

MatejLach commented Dec 5, 2014

@mdinger I tried with a fresh profile, it still happens.
What about using the CSS from Google Web Fonts? They have Fira Sans and fonts embedded from Google Web Fonts always work correctly for me.

@mdinger

This comment has been minimized.

Contributor

mdinger commented Dec 6, 2014

@MatejLach Ah, I didn't notice that you and @Gankro were describing the same issue. That makes sense then.

@steveklabnik

This comment has been minimized.

Member

steveklabnik commented Dec 8, 2014

This no longer cleanly merges, and I intend to revamp the Tasks guide before merging this all together anyway, so I'm giving this PR a close for now. @brson let's tallk automation sometime soon as well.

alexcrichton added a commit to alexcrichton/rust that referenced this pull request Jan 8, 2015

rollup merge of rust-lang#19897: steveklabnik/trpl
An updated version of rust-lang#19461

This version vendors steveklabnik/rustbook@731f7bf and builds it when building the docs. This is almost great, except my `make`-foo is poor, so I have my own personal paths in `mk/docs.mk`. How should I best get around that?

/cc @brson
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment