Configure Sphinx docs and Travis-CI deployment to GitHub Pages

[gnidan]

This PR has two parts:

• Sphinx docs set-up
• Deployment

Sphinx

Sphinx is an extensible docs generator. This PR enables extensions for:

• JSON schema support via sphinx-jsonschema
• Support for PlantUML diagrams via sphinxcontrib-plantuml
• Toggle-able dropdowns via sphinxcontrib-contentui

Deployment

This PR sets up Travis deployment to gh-pages so that anyone who opens a PR can preview their changes. For instance: Preview this PR!

Included script ./bin/deploy checks out the gh-pages branch and copies the built docs output into the directory structure on that branch:

• Builds directly on master copy to branch root, to resolve at ethpm.github.io/ethpm-spec/.
  (Note: this link won't work until this PR is merged)
• Commits on other branches and PRs are placed in ./contrib/<remote-fork-name>/<branch-name>, to resolve at ethpm.github.io/contrib/<remote-fork-name>/<branch-name>.

To enable this, I have create a single-purpose deploy key with repository write-access, encrypted it with Travis's public key, and configured the CI build to hook everything up. For reference, I've adapted a process described in this gist.

Other Notes

• Plug in validate.py into the Travis-CI build process, since that was previously not automated.
• This PR doesn't actually contain docs yet, to keep this work isolated.

[pipermerriam]

I'd highly recommend using read-the-docs over gh-pages for hosting. They have solid facilities for building and hosting the docs, including multiple versions across multiple releases, etc. And you can get rid of that entire deploy script.

[gnidan]

@pipermerriam I would prefer RTD also, but I have two concerns/questions:

• It'd be nice to support previews of any contributor's changes before they are merged.
• Can RTD run plantuml.jar for us, or more generally support custom themes and/or extensions?

It's been awhile since I've done research on the matter, but last I checked, this was lacking. Please advise!

[pipermerriam]

It just support custom themes, extensions, and in general, custom builds. dunno about plantuml.jar but I suspect it's doable.

[gnidan]

PlantUML is just there in case diagrams would be useful. It's certainly not a hard requirement. I just like diagrams. 🙃

I will research what the support is like with RTD these days. Thanks!

[pipermerriam]

Also found this with some quick searching. https://plantweb.readthedocs.io/

[gnidan]

Also found this with some quick searching. https://plantweb.readthedocs.io/

I'm aware of this tool, but it requires a PlantUML server. There's a public server, but I don't know about reliability, or any performance impact.

Anyway, it looks like there's an open issue readthedocs/readthedocs.org#407 for PlantUML support, but this RTD site seems to have it working (and from the looks of it, with the JAR self-hosted somehow? Unclear at first glance.)

UPDATE: Seems like it's supported out of the box now, and just undocumented? readthedocs/readthedocs.org#3885

[gnidan]

@pipermerriam Do you feel strongly against GitHub Pages, or just strongly in favor of RTD?

If it's the latter, I propose this as an initial solution, since it works and is arguably not too complex; we can always switch when it becomes clear that this project needs a more mature solution like RTD.

[gnidan]

For the other concern (the pre-merge previews), it seems like this is a requested feature, not yet available: readthedocs/readthedocs.org#2465

[pipermerriam]

@gnidan I'll defer to you. All that really matters is that there is reliably hosted documentation that is up-to-date.

[gnidan]

Thanks @pipermerriam. I am confident that this will suffice – Truffle's been using a similar GH pages build for almost a year without major problems.

Mind reviewing the implementation?

Also, anyone else have thoughts?

[pipermerriam]

It may not matter, but the docs build is outputing an error: https://travis-ci.org/ethpm/ethpm-spec/builds/377497652#L566

I'm surprised that the conf.py isn't throwing errors since the travis build is in a python3 environment.

[pipermerriam]

This is python2 unicode string syntax. We should probably be using python3 which doesn't have the u prefix.

[njgheorghita]

Looks good to me, I'm down with this GH pages setup - at least until we run into a reason to switch.
Maybe add a link to the docs at the top of the README?

[gnidan]

Re: build error: I forgot to include .gitkeep for _static and _templates because they're empty right now. Fix that and the string syntax.

@njgheorghita We should probably wait to add this to the README, since the docs are totally empty. I figure, we can set up the link once we've moved the package.spec.md into Sphinx.

I'll merge this tomorrow assuming no objections. Thank you very much!