During Cebit we had a lot of good talks. Such a fair isn't just nice for showing new features but it also is a great channel to get some feedback from our users.
One question we had was if there is any documentation for the methods opsi provides through the API.
The methods that are accessible through the webinterface / opsi-admin are defined in python-opsi.
python-opsi already contains documentation for some methods. Many methods are modelled after CRUD and follow the same patterns but some documentation does not hurt anybody. So I asked myself how can we make the existing documentation available?
The README holds instructions on how to build the documentation but why should everyone need to build their documentation?
One popular service for hosting documentation is readthedocs. They rely on Sphinx and this is what we already use for the documentation. It sounded great! So I thought I'd give it a try and see if we can host the documentation for python-opsi there.
But I could not get a complete build. At first everything looked great but I then realized that modules were missing and I investigated the logs. Looks like some of our dependencies were missing but the people at rtd had thought of that too and so I provided the required information.
Unfortunately we do have some requirements that are not a simple
pip install package away.
There are various ways recommend on how to work around but none of these did work for me in that case.
If installing the dependencies is a blocker... why don't we go somewhere all those dependencies are already present? The Continuous Integration environment we use has build nodes that fulfill our requirements! Building is not an issue there and the setup was a matter of a few minutes. Now now we need to think about publishing!
One of the jobs builds the documentation for opsi and prepares it for later deployment. Why not extend that job?
Now every new push to the stable branch of either the opsi documentation or python-opsi triggers a build. The build creates the documentation from asciidoc and then copies the latest documentation from python-opsi to the output directory before packing everything up for the publication.
Long story short... If you now want to take a look into to the python-opsi documentation it is all there.