Move build system to Nanoc

[gjtorikian]

This PR is a proposal to move the build system off of the proprietary, closed-source implementation of Atlas to the static-site generator Nanoc.

A reason for making this change is that Atlas is a huge black box. It's virtually impossible for anyone interested in making contributions to the content here to generate documentation locally that matches the online environment. Beyond that, there are numerous bugs, such as:

• Links not working
• Inconsistent titles
• Broken version switcher

This PR:

• Implements a Nanoc build system. Asciidoctor is still the primary markup format.
• Rearranges the directories so that they make sense for Nanoc. (Everything needs to be under a content folder.)
• Removes various Atlas assets and stylesheets that are unused.
• Sets up build tools and scripts to generate the docs. (script/bootstrap to fetch dependencies, script/server to start the docs locally, etc.)
• Adds a CI via html-proofer to ensure that no links are broken.

The one thing we lose with this switch is the ability for multiple outputs (currently HTML, PDF, Mobi, eBook). We've been tracking usages for all of these formats since July 2015, and there's virtually no one using Mobi or eBook. PDF has some usage, but it's still rather small compared to the overwhelming majority of HTML. Therefore, I think it's more appropriate to fix the immediate problem of allowing people to generate the docs locally. We should circle back to PDF generation via pandoc in the future.

Good docs are an important tool to help newcomers understand, contribute to, and make use of a project. I hope that by simplifying the build system here we'll see more content updates, as the mystery of how it all works should be eliminated.

/cc @thedaniel @izuzak @lee-dohm

Not sure who else to cc!

[lee-dohm]

ul font size appears too large:

http://flight-manual.atom.io/using-atom/sections/basic-customization/

[gjtorikian]

It would be nice to have section pages render TOCs in the markdown, like in the old layout.

Not sure I follow. Could you show me?

[thedaniel]

I realized I was imagining things and just removed their anchor tags in the following commit :) I had thought I recalled section summaries having links to their items but couldn't find it on atom.io after all. 

https://github.com/thedaniel

On Mon, Mar 14, 2016 at 11:12 AM -0700, "Garen Torikian" notifications@github.com wrote:

It would be nice to have section pages render TOCs in the markdown, like in the old layout.

Not sure I follow. Could you show me?

—
Reply to this email directly or view it on GitHub.

[simurai]

Question: If you click on "Documentation" form http://flight-manual.atom.io/, should it got to https://atom.io/docs? That page will stay as is, right?

There wouldn't be a link to the index, but maybe not needed since it's the same as the nav on the side.

[gjtorikian]

Yeah, I think that link can stay the same.

[simurai]

@lee-dohm ul font size appears too large:

Should be fixed. Now also shows bullets:

[thedaniel]

I think it's time to hit the merge button.