Henry

A wrapper around Sphinx and Docker

Prologue

Having to mess with Python, Virtualenv and Sphinx is not effortless !

If you work with reST based and Sphinx build documentation a lot, this may not that obvious for you.

via GIPHY

Background

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 !! :)

Conclusion

We need an easier way to archive this, with less dependencies and moving parts as possible !

Solution

Picture of henry cli

What Is Henry

henry is a command-line wrapper written in Go with an friendly and clear interface.

Features

  • 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.

Dependencies

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.

Why Golang

Yeah, why I went with Golang ?

Several reasons:

  • 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.