If you work with reST based and Sphinx build documentation a lot, this may not that obvious for you.
As some of you may know, I am also a bit involved into Plone.
The docs of Plone are in reST and build with Sphinx.
Since I work quite a bit on the docs I have a customized setup, which involves:
- Custom Sublime 3 setup for Plone documentation
- Custom Sphinx setup running in Docker, based on a ‘hacked’ version of Papyrus
- Githooks, a lot of them, running tests against the docs I commit
I tend to forget that most of the awesome people who contribute do not have this …
Recently a new contributor worked on some improvements, thanks btw ! :)
Before opening a pull request, this person wanted to review the made changes as build HTML to make sure, that is looks OK with our custom theme.
As for this moment there is no ‘uncomplicated’ way to do that for the docs of Plone.
Of course you can run Papyrus local on your machine, but this is not suited for everyone. Papyrus is way more than just building the docs.
Papyrus will for example download Plone and run a whole robot framework test suite against Plone and the docs.
This is way to complicated and simply not needed.
Another person suggested to download Python, Virtualenv, Sphinx, configure Sphinx and run it against the docs repository. This is not suited either, this is may OK for developers but not for people who do not use all this every day.
Further, because of the way how Plone collects and build its docs, this is really, really hard to setup, if do not have experience with Sphinx. Funny site note, the person who suggested this was also not able to get it working :) No Offense !! :)
We need an easier way to archive this, with less dependencies and moving parts as possible !
What Is Henry
henry is a command-line wrapper written in Go with an friendly and clear interface.
- Builds HTML (default)
- Builds HTML in test mode (nitpicky)
- Basic reST checks
That is all, nothing more, … yet !
The main focus is on getting a quick visual how your docs will look like, this is not meant to be a full blown testing tool. There is the idea to add a configuration file later, that will let you configure certain things. I would like to add a check, that henry only checks/builds the files you want to commit.
One, and that is Docker.
All the lifting in the background is done by plone-docsbuilder.
This is IMHO good, because that is the same container which will be used in CI for the docs. If we add a new feature to this container, we can also consider to add it to henry.
If you know docker, you do not need henry, henry is a wrapper around.
Yeah, why I went with Golang ?
- I wanted to write something in Golang
- I can release binaries
Because of being able to release compiled binaries for various Operating Systems it makes it easier to install.
No messing with versions and such stuff.