search

ethpm / ethpm-spec

Ethereum Package Manager http://ethpm.github.io/ethpm-spec/
165 stars 30 forks source link

Configure Sphinx docs and Travis-CI deployment to GitHub Pages #90

Closed gnidan closed 6 years ago

gnidan commented 6 years ago

This PR has two parts:

Sphinx

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

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:

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

pipermerriam commented 6 years ago

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 commented 6 years ago

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

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

pipermerriam commented 6 years ago

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

gnidan commented 6 years ago

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 commented 6 years ago

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

gnidan commented 6 years ago

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 https://github.com/rtfd/readthedocs.org/issues/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? https://github.com/rtfd/readthedocs.org/issues/3885

gnidan commented 6 years ago

@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 commented 6 years ago

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

pipermerriam commented 6 years ago

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

gnidan commented 6 years ago

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?

gnidan commented 6 years ago

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!