Script for building every first-level subsection of the Sphinx project as separate PDF. Look here for details: http://wswld.net/2015/04/03/humble-collection-of-python-sphinx-gotchas-part-ii/

build.py

#!/usr/bin/python
# -*- coding: utf-8 -*-
 
import os
import errno
import json
import argparse
import datetime
 
parser = argparse.ArgumentParser(description='Builds the documentation project.')
parser.add_argument(
    '--test', '-t',
    dest='test',
    action='store_true',
    help="Build the test version (sends output to the test server)."
)
parser.add_argument(
    '--local', '-l',
    dest='local',
    action='store_true',
    help="Build the local version (doesn't send output anywhere)."
)
parser.add_argument(
    '--no-pdf', '-p',
    dest='nopdf',
    action='store_true',
    help="Don't build PDFs (to save time, when debugging HTML)."
)
parser.add_argument(
    '--verbose', '-v',
    dest='verbose',
    action='store_true',
    help="Write output to log or to screen."
)
args = parser.parse_args()
 
# sets the default for what to do with log output if not verbose
log = {
'html': ' > ../html.log'
}
if args.verbose:
    log['html'] = ''
 
def mkdir(path):
    """
    The function to make directories.
    """
    try:
        os.makedirs(path)
    except OSError as exc:
        if exc.errno == errno.EEXIST and os.path.isdir(path):
            pass
        else:
            raise
 
def sh(script):
    """
    Simple wrapper for bash
    """
    os.system("bash -c '%s'" % script)
 
 
if __name__ == "__main__":
 
    # finds the project folder and cd into that
    pwd = os.path.abspath(os.path.dirname(__file__))
    os.chdir(pwd)
 
    # opens targets.json and forms the list of targets
    json_data = open("targets.json").read()
    trgt_list = json.loads(json_data)
 
    # adds _tmp folder
    if os.path.exists(os.path.dirname("_tmp/")):
        sh('rm -r _tmp/')
        print "-- _tmp/"
    mkdir('_tmp/')
    print "++ _tmp/"
 
    # adds _metatmp folder
    if os.path.exists(os.path.dirname("_metatmp/")):
        sh('rm -r _metatmp/')
        print "-- _metatmp/"
    mkdir('_metatmp/')
    print "++ _metatmp/"
 
    # adds _pdf folder
    if os.path.exists(os.path.dirname("_pdf/")):
        sh('rm -r _pdf/')
        print "-- _pdf/"
    mkdir('_pdf')
    print "++ _pdf/"
 
    # copies everything into _metatmp
    sh('rsync -r --exclude _metatmp/ * _metatmp/')
 
    os.chdir('_tmp')
    print ">> _tmp"
 
    if args.nopdf != True:
 
        for trgt in trgt_list:
            uptrgt = trgt_list[trgt].encode('utf-8')
            # forms the list of versions based on project subdirectories
            vrsn_list = os.walk('../%s/' % trgt).next()[1]
            #builds PDFs for every version in version list
            for vrsn in vrsn_list:
                sh('rm -rf *')
 
                # copies all the necessary files including temp.py as conf.py
                sh('cp -r ../%s/%s/* .' % (trgt, vrsn))
                sh('cp ../temp.py conf.py')
                sh('cp ../pdf_logo.png .')
                sh('cp ../Makefile .')
 
                # sets target names and version in conf file for each subproject
                sh("find \"conf.py\" -print -exec sed -i'' \"s#&TRGT#%s#g\" {} \; >/dev/null" % trgt)
                sh("find \"conf.py\" -print -exec sed -i'' \"s#&UPTRGT#%s#g\" {} \; >/dev/null" % uptrgt)
                sh("find \"conf.py\" -print -exec sed -i'' \"s#&VRSN#%s#g\" {} \; >/dev/null" % vrsn)
 
                if args.verbose:
                    log[trgt + vrsn] = ''
                else:
                    log[trgt + vrsn] = ' > %s%s_pdf.log' % (trgt, vrsn)
 
                print("\033[36m")
                sh(
                    'make latexpdf %s && echo "\033[1;32mPRODUCED: %s%s.pdf\033[0m" || '
                    'echo "\033[1;31mNOT PRODUCED: %s%s.pdf\033[0m"' % (log[trgt + vrsn], trgt, vrsn, trgt, vrsn))
                print("\033[0m")
 
                # adding links to PDF to the subsection index.rst
                sh("find '../_metatmp/%s/%s/index.rst' -print -exec sed -i'' \"s/.. &//g\" {} \; "
                   ">/dev/null" % (trgt, vrsn))
                sh("find '../_metatmp/%s/%s/index.rst' -print -exec sed -i'' \"s/TARGET/%s%s/g\" {} \; "
                   ">/dev/null" % (trgt, vrsn, trgt, vrsn))
                # copies the PDF file to the _pdf folder for temporary storage
                sh('cp _build/latex/%s.pdf ../_pdf/%s%s.pdf' % (trgt, trgt, vrsn))
 
    os.chdir('../_metatmp')
    print("\033[35m")
    sh('make html %s && echo "\033[1;32mPRODUCED:HTML\033[0m" || echo "\033[1;31mNOT PRODUCED: HTML\033[0m"' % log[
        'html'])
    print("\033[0m")
    if args.nopdf != True:
 
        for trgt in trgt_list:
            vrsn_list = os.walk('%s/' % trgt).next()[1]
            for vrsn in vrsn_list:
                # copies the produced PDFs from the _pdf folder to the subsection root
                sh('cp ../_pdf/%s%s.pdf _build/html/%s/%s/' % (trgt, vrsn, trgt, vrsn))
 
    os.chdir('..')
 
    if args.test:
        sh('echo "TEST VERSION\nPRODUCED:%s" > _metatmp/_build/html/VRSN' % datetime.datetime.now().strftime(
            '%Y-%m-%d %H:%M:%S'))
        sh("cp -r _metatmp/_build/html/* /var/www/html/")
    elif args.local:
        pass
    else:
        sh("scp -i ../id_rsa -r _metatmp/_build/html/* serveruser@server:/server/path/")
 
    sh('rm -r _tmp/')
    sh('rm -r _pdf/')

targets.json

{
  "foo" : "Foo Foo",
  "bar" : "Barrington"
}