From 68b8837a8d8b37767a604d136b622ac51733aa09 Mon Sep 17 00:00:00 2001
From: lethosor <lethosor@gmail.com>
Date: Fri, 22 Jul 2022 00:30:36 -0400
Subject: [PATCH] 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
---
 docs/build-pdf.sh |  4 +--
 docs/build.py     | 90 +++++++++++++++++++++++++++++++++++++++++++++++
 docs/build.sh     |  5 +--
 3 files changed, 92 insertions(+), 7 deletions(-)
 create mode 100755 docs/build.py

diff --git a/docs/build-pdf.sh b/docs/build-pdf.sh
index 735ef2faa..a7527cb34 100755
--- a/docs/build-pdf.sh
+++ b/docs/build-pdf.sh
@@ -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 "$@"
diff --git a/docs/build.py b/docs/build.py
new file mode 100755
index 000000000..2a42d0968
--- /dev/null
+++ b/docs/build.py
@@ -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('')
diff --git a/docs/build.sh b/docs/build.sh
index 28182d9c0..7a6bd0b33 100755
--- a/docs/build.sh
+++ b/docs/build.sh
@@ -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 "$@"