Sphinx doc publishing workflow

[deis]

Sphinx doc publishing workflow

[bengrunfeld]

Re static HTML files inside of a Wordpress installation, you can just drop them as is into the Deis theme
(or a subdirectory of it) and access them via an absolute link. The only issue is that Permalinks don't work via
going with this route, so instead of deis.io/documentation/how-to-scale/, it would be deis.io/wp-content/themes/deis/documentation/how-to-scale.html

As long as you don't mind the longer URL, there is no issue.

The Wordpress plugins that I've looked at so far that deal with static HTML pages all seem to push the pages
into the WP database one way or another,

A possible solution is that we use Apache mod_rewrite to re-write the URL's manually. I'm sure an automation
script for just that would be pretty easy to write. This keeps manual handling to a minimum. The only question here is if messing with mod_rewrite would cause a conflict with Wordpress, although we would be able to test this locally first.

[gabrtv]

We need a solution for hosting docs.deis.io using static files. Options are:

1. S3 static website hosting
2. WPEngine static hosting on a new site (with git push)
3. Some other static hosting solution

@bengrunfeld will research option 2, which could be the easiest (and cheapest) integration.

[mboersma]

The process is as follows:

• push code to github
• github fires a service hook request to readthedocs.org (see Settings -> Service Hooks for the deis project)
• readthedocs.org runs Sphinx and builds the docs (log in as opdemand to alter the build setup)
• docs.deis.io is an alias for deis.readthedocs.org

So really no work is currently required--every code push will update the docs automatically, after a couple minutes' lag. At some point when we have settled into a more deliberate release schedule, we will need to alter this process to make docs for the most recently released version be "sticky," and have a way to get to in-development docs.