Henry - Documentation - Test Builds¶
A wrapper written in Golang around Sphinx and Docker.
About¶
The main idea behind henry is to make it a bit more pleasant and maybe less hard to install Sphinx.
Installing Sphinx can be overwhelming, especially if you do not use it all the time.
You need to install Python, figure out the whole virtualenv thing and such stuff.
Imagine you are a new contributor to a open source project and you worked hard on a piece of reST based documentation.
You followed the style-guide and you checked for typos, grammatic, tone, wording and so on, you even used the reST preview mode of your editor to get a first impression of how it looks.
AWESOME !
Before you create your pull request you want to make sure that it will look OK if you build is as HTML with the theme of your documentation.
Maybe you will have to change some headers or add a line break or do something else.
According to the docs of your project, you have to download and install Sphinx into a virtualenv, you have to make sure to use the right versions, you need Python and so on. HELP!!??
“I am not a developer, I work with CSS, all I wanted to do was to improve the docs part about theming.”
You are right !
We need an easier way to archive this, with less dependencies and moving parts as possible !
Usage¶
Release Notes¶
0.0.1-alpha.2¶
Second alpha release of henry.
This is a pre-release and meant for testing !
Changes¶
- Debug mode by default not quitting on errors, anymore, use
henry debug -sfor that.
New¶
- Start with documentation
- Add mode ‘debug-strict’
Updates¶
- Update vendor dependencies to latest versions
Fixes¶
- Fixed debug mode
Known Limitations¶
- Docs are not finished
- Missing tests
- Missing checks
- Wording of descriptions and such
0.0.1-alpha.1¶
First alpha release of henry.
This release is a pre-release and meant for testing.
Features¶
- html: builds html
- debug: builds html in debug mode, build will stop on erros.
- serve: automatically rebuilds the docs on every detected change
Known Limitations¶
- missing tests
- missing checks
- wording of descriptions and such
Development¶
Warning
These docs are WIP !
Vendoring¶
Use: govendor.
History¶
govendor init
govendor add +external
govendor install +local
All of this in the /root of the repo
Release¶
Use https://github.com/goreleaser/goreleaser for releases.
Testing¶
For testing use gox -> https://github.com/mitchellh/gox
Makking A Release¶
- create branch
- tag branch like -> git tag 0.0.1-alpha.1
- push tag like -> git push origin 0.0.1-alpha.1
- export GitHub token -> export GITHUB_TOKEN=123456
- run goreleaser: gorelease
Check and adjust setting on GitHub release page
Internals¶
henry is a wrapper on steroids around Sphinx and Docker written in golang.
The main motivation behind henry is to make it less hassle as possible to get a visual impression of your docs.
henry uses Cobra as base.
Cobra is a library providing a simple interface to create powerful modern CLI interfaces similar to git & go tools.
We use Cobra to run certain (Sphinx) commands in Docker.
If you don’t want to deal with installing Sphinx over and over again ....
No messing with virtualenv, pip, etc.
Henry can help you getting a quick visual how your docs will look like.
Features¶
- Builds HTML (default)
- Builds HTML in debug mode (reST checks)
Note
Henry evolved out of the Plone documentation project.
For the moment there is no ‘easy’ way to use your own theme or add-ons !
This will change in the future !!
