You know, precise and correct documentation is the one kept in synch with the source code automatically.
There are many ways of doing that, many kinds of documentation. Here I’ll show you how to publish content in GitHub Pages after a successful build. In this case, the content is a API specification generated when running acceptance tests.
How to do it?
- Put the content you want to be published in the /docs dir
- Go to Settings, find the GitHub Pages section, and select Source to master branch /docs folder, then press Save
- Push it to master.
The content in the /docs will be available at
eHelp is configured to put its generated specs in the /docs folder. Every time we push to master, its GitHub Page gets updated. This way, its specs are always published and always in sync.
The Past – In Case You Are Curious
(It’s nice to see that things are getting simpler.)
Not so long ago, I wrote a post (Tip #1) explaining how to achieve the same result using Travis CI and some scripting help. This little project is configured the old way: see travis.yml and update-gh-pages.sh files.
You can find more information at GitHub help pages:
(First of all install Travis CLI if you haven’t done it yet.)
Tip 1: Updating GitHub Project Pages Automatically after Building
Important note! There’s a much easier way of doing virtually the same thing explained here. The only difference is that GithHub Pages will only be updated if the build is green when following the instructions bellow, as opposed to updating Pages as soon as something is pushed to the branch master.
It’s pretty nice and very rare to have documentation up-to-date with the code base. Using Yatspec, GitHub and Travis CI (all part of my current work environment), it’s easy to test, document and publish the documentation automatically after a build (like this and this), and keep the docs always in synch with the code.
Let’s Do It…
1) (Obviously) Have Some Content to Publish
As mentioned before, the content I’m interested in publishing is the specification generated by Yatspec based on acceptance tests.
2) Configure GitHub Project Pages
Continue reading “Travis CI Tips”
(Note: this post is still in beta.)
It’s great how easy these days is to have a work environment that supports agile process (continuous integration/delivery, [B|T]DD) almost for free.
The fact alone that all this stuff is running on someone else machine is great. But, most important, there’s no need to spend a penny or spend very little compared to having your own infrastructure and people maintaining it (even if people means just you).
Continuous Integration & Delivery
I’m using GitHub as repository, and Travis CI for continuous integration (configurable in minutes) to test and build my projects as soon as I push code to GitHub.
Continue reading “Release Often & Automate Everything in the Process (beta)”