dfhack/docs/build.py

93 lines
3.4 KiB
Python

#!/usr/bin/env python3
# for help, run: python3 build.py --help
import argparse
import os
import subprocess
import sys
class SphinxOutputFormat:
def __init__(self, name, pre_args):
self.name = str(name)
self.pre_args = tuple(pre_args)
@property
def args(self):
output_dir = os.path.join('docs', self.name)
artifacts_dir = os.path.join('build', 'docs', self.name) # for artifacts not part of the final documentation
return [
*self.pre_args,
'.', # source dir
output_dir,
'-d', artifacts_dir,
'-w', os.path.join(artifacts_dir, 'sphinx-warnings.txt'),
]
OUTPUT_FORMATS = {
'html': SphinxOutputFormat('html', pre_args=['-b', 'html']),
'text': SphinxOutputFormat('text', pre_args=['-b', 'text']),
'pdf': SphinxOutputFormat('pdf', pre_args=['-M', 'latexpdf']),
'xml': SphinxOutputFormat('xml', pre_args=['-b', 'xml']),
'pseudoxml': SphinxOutputFormat('pseudoxml', pre_args=['-b', 'pseudoxml']),
}
def _parse_known_args(parser, source_args):
# pass along any arguments after '--'
ignored_args = []
if '--' in source_args:
source_args, ignored_args = source_args[:source_args.index('--')], source_args[source_args.index('--')+1:]
args, forward_args = parser.parse_known_args(source_args)
forward_args += ignored_args
return args, forward_args
def parse_args(source_args):
def output_format(s):
if s in OUTPUT_FORMATS:
return s
raise ValueError
parser = argparse.ArgumentParser(usage='%(prog)s [{} ...] [options] [--] [sphinx_options]'.format('|'.join(OUTPUT_FORMATS.keys())), description='''
DFHack wrapper around sphinx-build.
Any unrecognized options are passed directly to sphinx-build, as well as any
options following a '--' argument, if specified.
''')
parser.add_argument('format', nargs='*', type=output_format, action='append',
help='Documentation format(s) to build - choose from {}'.format(', '.join(OUTPUT_FORMATS.keys())))
parser.add_argument('-E', '--clean', action='store_true',
help='Re-read all input files')
parser.add_argument('--sphinx', type=str, default=os.environ.get('SPHINX', 'sphinx-build'),
help='Sphinx executable to run [environment variable: SPHINX; default: "sphinx-build"]')
parser.add_argument('-j', '--jobs', type=str, default=os.environ.get('JOBS', 'auto'),
help='Number of Sphinx threads to run [environment variable: JOBS; default: "auto"]')
parser.add_argument('--debug', action='store_true',
help='Log commands that are run, etc.')
args, forward_args = _parse_known_args(parser, source_args)
# work around weirdness with list args
args.format = args.format[0]
if not args.format:
args.format = ['html']
return args, forward_args
if __name__ == '__main__':
os.chdir(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
if not os.path.isfile('conf.py'):
print('Could not find conf.py', file=sys.stderr)
exit(1)
args, forward_args = parse_args(sys.argv[1:])
for format_name in args.format:
command = [args.sphinx] + OUTPUT_FORMATS[format_name].args + ['-j', args.jobs]
if args.clean:
command += ['-E']
command += forward_args
if args.debug:
print('Building:', format_name)
print('Running:', command)
subprocess.call(command)
print('')