Auto-documenting your Pharo-projects

This blogpost is about how to combine (preferably GiHub-hosted) Pharo project, Travis-CI testing, and Pharo web documentation.

To test your project on Travis, you need some GitHub repo that will trigger a build. Now the build itself is pretty simple, you just need to install 32bit libs and then use features of Zeroconf scripts. A snippet of the .travis.yml config file is available as gist.

Now to generate and store your documentation after build succeeds, you have do add 3 steps to after_success: section in .travis.yml.

1. Load WebDoc into your image. This is easy:

   ./pharo Pharo.image config http://www.smalltalkhub.com/mc/Pharo/MetaRepoForPharo30/main ConfigurationOfWebDoc --install=stable

2. Generate documentation for your project:

   ./pharo Pharo.image webdoc --export=$VERSION "^$PROJECT.*"

   here --export value is a directory where WebDoc should export the documentation. Here I use the $VERSION variable from .travis.yml to have both development and stable doc. Also you have to pass a regex against which package names will be matched and if so - exported as doc. I re-use $PROJECT variable and include '^' in regex to capture beginning of the string and avoid exporting configuration. Depending on your naming conventions "$PROJECT-.*" may work for you too.
3. Now you have to publish your doc somewhere. One free option is to use GitHub pages for your project. For this you can follow a tutorial on Sharing Travis-CI generated files. Make sure that if you decide to generate a different doc for each version, you copy whole directory (specifying it with variable name) e.g.:

   cp -R $VERSION $HOME/$VERSION
   ...
   cp -Rf $HOME/$VERSION/ .

This is it. I hope that we will improve WebDoc soon, as well as all project-related infrastructure.

P.S. Yes, this can be achieved with more ease by using Pharo-Contribution Jenkins, but the philosophy of Sleepy Coders states that a reader can over a tutorial during a night and complete it without having to ask some permissions and so on (as most permission-related people sleep during a night)

P.P.S. At the moment of writing I'm using it on my project VnaExporter to export the documentation of it.