deploy to github-pages

[casperdcl]

• add continuous integration (CI) (fixed by add CI #56 & basic Circle-CI build #57)
  • get CI to regularly build the site
  • test builds of branches and PRs before merge
  • full build env control
• deploy mkdocs-generated static site directly to gh-pages
  • get CI to automatically deploy the site to gh-pages branch
  • http://docs.openworm.org is configured to point to github.io
    • update openworm.org's CNAME DNS record for the docs subdomain to point to openworm.github.io as per https://help.github.com/en/github/working-with-github-pages/configuring-a-custom-domain-for-your-github-pages-site (i.e. make docs.openworm.org point to openworm_docs)
  • openworm.github.io/openworm_docs is configured to expect http://docs.openworm.org (without affecting openworm.github.io expecting http://openworm.org)
  • no dependency on any other web services
• fixes use gh-pages #60
• related to website not updated from this repo #64

We already rely on GitHub pages for the main site (https://github.com/openworm/openworm.github.io).

[mwatts15]

Please add some comments where you're using keys or values that are from or dictated by external systems (e.g., "Why do we need to filter out gh-pages"). We want our documentation build system to be well-documented as well!

(Also, if we're abandoning rtd.org, are you thinking of a solution for hosting docs that are work-in-progress? Is that just another gh-pages* branch? We will have releases of OpenWorm, so I expect we'll have a long-lived development branch for docs as well. Not expecting it for this review though.)

[casperdcl]

@mwatts15 work-in-progress docs are already accessible via the circleci builds I set up! for example, https://407-12814245-gh.circle-artifacts.com/0/home/circleci/repo/site/gsod19/repos/index.html is from navigating the artifact tree in https://circleci.com/gh/openworm/openworm_docs/407#artifacts/containers/0 which is WIP from #58

[mwatts15]

@mwatts15 work-in-progress docs are already accessible via the circleci builds I set up! for example, https://407-12814245-gh.circle-artifacts.com/0/home/circleci/repo/site/gsod19/repos/index.html is from navigating the artifact tree in https://circleci.com/gh/openworm/openworm_docs/407#artifacts/containers/0 which is WIP from #58

That's pretty sub-optimal: That doesn't give me a stable link to the latest documentation and the Circle-CI artifact view isn't reflective of the target deployment. I can't use most of the hyperlinks from there either.

[casperdcl]

@mwatts15 I agree it's clunky - I'll open a new issue regarding making it easier to see. Shouldn't be too hard to find a solution (depending on how important you think it is).