Replace docs/build*.sh with more flexible build.py

Notable changes:
- can build any combination of output formats in series
- `-E` is no longer passed by default to aid in development, but can be passed
  manually
develop
lethosor 2022-07-22 00:30:36 -04:00
parent 0a44ef7ffb
commit 68b8837a8d
No known key found for this signature in database
GPG Key ID: 76A269552F4F58C1
3 changed files with 92 additions and 7 deletions

@ -9,6 +9,4 @@
# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
cd $(dirname "$0")
cd ..
"${SPHINX:-sphinx-build}" -M latexpdf -d build/docs/pdf . docs/pdf -w build/docs/pdf/_sphinx-warnings.txt -j "${JOBS:-auto}" "$@"
python3 build.py pdf "$@"

@ -0,0 +1,90 @@
#!/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']),
}
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('')

@ -9,7 +9,4 @@
# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
cd $(dirname "$0")
cd ..
"${SPHINX:-sphinx-build}" -E -b html -d build/docs/html . docs/html -w build/docs/html/_sphinx-warnings.txt -j "${JOBS:-auto}" "$@"
"${SPHINX:-sphinx-build}" -E -b text -d build/docs/text . docs/text -w build/docs/text/_sphinx-warnings.txt -j "${JOBS:-auto}" "$@"
python3 build.py html text "$@"