Home » Python » Automating Python documentation builds

For the hephaestus project I have been working on automating the documentation build process (which uses brilliant ‘doxygen‘ package).

The doxygen run outputs HTML and LaTeX, but doesn’t do anything with it. I want:
– automatic LaTeX -> PDF conversion
– automatic upload to http://ndonaghy.com/hephaestus/docs

I am happy, of course, to handle the git repository by hand. Incidentally, you can find this build script and the doxygen configuration file at the hephaestus repository on GitHub.

Here is what I came up with:

#!/usr/bin/env python
import os

print("Building documentation...")
print("Cleaning up...")
os.system("cd docs/; rm -r html/ latex/")
print("Running doxygen...")
os.system("cd docs/; doxygen config.dox")  # run doxygen with our configuration file
print("doxygen finished, running pdflatex...")
os.system("cd docs/latex; make")  # run make in the latex output directory to generate a PDF
print("Created PDF...")
os.system("ls -lh docs/latex/refman.pdf")
print("Uploading PDF to http://ndonaghy.com/hephaestus/docs")
os.system("scp docs/latex/refman.pdf niall@ndonaghy.com:~/ndonaghy/hephaestus/docs")
print("...done!")
print("Creating HTML tarball...")
os.system("tar cvzf html.tar.gz docs/html/")
print("Uploading...")
os.system("scp html.tar.gz niall@ndonaghy.com:~/ndonaghy/hephaestus")
print("Expanding...")
os.system("ssh niall@ndonaghy.com 'cd ~/ndonaghy/hephaestus/docs/html; rm -r *; cd ~/ndonaghy/hephaestus; tar xvzf html.tar.gz; rm html.tar.gz'")
print("Cleaning up...")
os.system("rm html.tar.gz")
print("\n...done!\n")

Example run:

$ ./builddocs.py 
Building documentation...
Cleaning up...
Running doxygen...
<doxygen output>
doxygen finished, running pdflatex...
<LaTeX output>
Output written on refman.pdf (67 pages, 334223 bytes).
Created PDF...
-rw-r--r-- 1 niall niall 327K Apr 26 03:50 docs/latex/refman.pdf
Uploading PDF to http://ndonaghy.com/hephaestus/docs
refman.pdf                                                                                                                                                                                                 100%  326KB 326.4KB/s   00:00    
...done!
Creating HTML tarball...
docs/html/
docs/html/classlib_1_1Interpreter__scan_1_1Interpreter__scan_ab0f50c851934d3a08dbfb8400d03420c_cgraph.md5
docs/html/Interpreter__scan_8py.js
<snip>
Uploading...
html.tar.gz                                                                                                                                                                                                100%  439KB 439.1KB/s   00:00    
Expanding...
<snip>
Cleaning up...

...done!