Create documentation site with vuepress (#1454)

[nklayman]

Adds a documentation/info site, powered by vuepress. Pages are written in markdown, and then converted to static html. Start dev server with npm run docs:dev. Build site with npm run docs:build (outputs to docs/.vuepress/dist). Versioning is handled by requesting the releases.json (hosted by the docs site, located in docs/.vuepress/public). It creates a versions dropdown with links to url/v${version}. Each version of docs would need to be published to the proper path. Hosting may need extra configuration as well, and the base configuration likely needs to be set.

[nklayman]

It also has a version script that will update the releases.json automatically.

[novemberborn]

Thanks for making the PR @nklayman. It may take me a little while to get round to reviewing this and considering how we'd publish to https://zeit.co/now.

[novemberborn]

This looks rather nice @nklayman!

Does the theme need to be committed? It looks to be the default theme so won't it come with the vuepress dependency?

Do we need to nest the Markdown files or can they stay in docs? You made a fair amount of changes to the Markdown syntax. Is that for compatibility with Vuepress? The index.md files look like duplicates of other content?

Could you remind me how we need to lay out the versions? I'm thinking that if we go with ZEIT's Now, we could have a build process that uses the GitHub API to select the Markdown files for each release, puts them in the right location and then builds a static site that includes the documentation of all versions. Does that sound about right to you?

[nklayman]

@novemberborn The reason I had to eject the default theme was to add the version selector dropdown. vuejs/vuepress#100 is a similar issue.

The docs are nested so they fall under different sections for navigation. There is the homepage, the guide section, and the recipes section.

The markdown changes were not intentional. I think prettier changed some things, I have it set to auto-format my code.

The root index.md is the regular readme, but without the install instructions. Those were moved to guide/index.md. The recipes/index.md is just a table of contents.

As for versioning, my original plan was to keep an archive of all the docs versions in ava.li/vx.x.x. The vuepress base config option needs to be set to vx.x.x for each archive build, however. The navigation bar has a dropdown that lists all versions of ava that link to the proper page. The versions get pulled from the docs/.vuepress/public/releases.json. This file is updated automatically by a version script. Your option might be easier to deploy as you won't need the releases.json or need to set the base config option. However, the builds might get really long if you are building multiple versions worth of docs. Unfortunately, vuepress does not have versioning support, so this is all kind of a hack. Vuepress v1.x might support it (or support could be added with a plugin), so that might fix this.

[novemberborn]

Hi @nklayman, sorry I haven't gotten round to picking this up again.

[novemberborn]

Hey @nklayman, I'm so sorry for ignoring this for so very long. I think the time commitment required on my part to review and then ship this turned out to be too much. That's happened with some other AVA PRs as well. I'm trying to encourage a more iterative approach that should result in smaller changes that are easier to ship.

It's probably for the best to close this PR now. Sorry to disappoint.