mozilla/rust — pull request #14245 by TheHydroImpulse (2014-05-16 08:21:09+00:00)
Title: Curated Doc Refactoring

This isn't ready for prime time yet, feedback is super important in areas like this, so that's what I'm looking for.

This is in relation to the [Splitting the Docs](http://article.gmane.org/gmane.comp.lang.rust.devel/9740) thread I posted to the mailing list.

In summary, this will replace the current *curated* documentation with a more appropriate system. This introduces [nanoc](http://nanoc.ws/) as the static site generator. There's no particularly huge reasons why nanoc was chosen, it works pretty well, and Github uses it for it's developer documentation.

There's two parts to this system:

* Nanoc Site
* Validator

Ensuring that the code blocks are legitimate Rust code is super important. The validator takes a directory as an argument `./validator ./dir` and walks the files and validates them. It's currently intended for Markdown files, but it can be extended for other uses. That's all it does. It's still somewhat rough and not perfect (could use some parallelism to speed it up).

![screenshot 2014-05-16 02 02 46](https://cloud.githubusercontent.com/assets/565790/2994626/8c307d38-dcd0-11e3-9bb9-0e49977b3015.png)

You can also [view a live version](http://rust-docs.s3-website-us-west-2.amazonaws.com/).

The ultimate goal is to provide a better user experience for new comers. Currently, we have a few problems:

* Tutorial is a giant page where everything was shoved into
* No direction at all! A user can easily get overwhelmed at massive pages like that.
* Secondary guides are almost invisible. I certainly didn't notice the links at the bottom for a while.
* Adding more information requires more work than is needed.

Thus, turning to a more extensible platform would allow us to control the user through each step of the process. I'm turning to the [Julia docs](http://docs.julialang.org/en/release-0.2/manual/) as an example.

## Dependencies

Unfortunately (perhaps delegation is a good thing), new dependencies emerge.

* Ruby is required (I specified 2.1.1, but if 1.9 is more appropriate, then I can change it)
* Bundler (to ease the pain of managing the gems)
* Pandoc (I believe this is already currently being used by Rust?)

---

**Note:** This new system is not tied to Rust in any way. Meaning, doing `make check` or running the standard commands does not initiate the new docs. They're isolated for the time being (and because I haven't made my strides into the wonderlands of Rust's makefiles).

---

## Todo

* Organize the content into guides/categories (`introduction`, `syntax`, etc...).
* Polish the validator (perhaps allow it to check multiple files at a time).
* Tie the new system into the rest of Rust.
* Polish the design

Overall, I'm pretty content with the simplistic design, similar to how the current docs are. It's not perfect yet, but the typography feels solid and doesn't require external fonts.