[babl] build: improve doc build - change build option to auto/true/false - auto=false if cross build true o

[Øyvind "pippin" Kolås <ok src gnome org>]

commit 58e2a1135e3811a3ddcaf93af0f2572e137ce42e
Author: John Marshall <jtm home gmail com>
Date:   Wed May 20 12:34:44 2020 +0100

    build: improve doc build
    - change build option to auto/true/false
    - auto=false if cross build true otherwise
    - replace xml_insert.sh with python script to allow doc gen on msys

 docs/meson.build    | 200 +++++++++++++++++++++-------------------------------
 meson.build         |  24 +++++--
 meson_options.txt   |   4 +-
 tools/xml-insert.py | 110 +++++++++++++++++++++++++++++
 4 files changed, 208 insertions(+), 130 deletions(-)
---
diff --git a/docs/meson.build b/docs/meson.build
index 01b6c3093..74984b0c5 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -5,7 +5,10 @@ location= 'public_html/babl'
 scptarget = host + ':' + location + '/'
 
 
-xml_insert = find_program(join_paths('tools', 'xml_insert.sh'))
+xml_insert = find_program(
+  meson.source_root() / 'tools' / 'xml-insert.py',
+  native: true
+)
 
 index_static_html = configure_file(
   input : 'index-static.html.in',
@@ -20,130 +23,85 @@ babl_css = configure_file(
 )
 
 index_html_tmp_env = [
-  'BABL_PATH='+ join_paths(meson.build_root(), 'extensions'),
+  'BABL_PATH=' + meson.build_root() / 'extensions',
 ]
 
-index_html_tmp = custom_target('index.html.tmp',
-  input : [ babl_html_dump, ],
-  output: [ 'index.html.tmp', ],
-  command: [
-    env_bin,
-    index_html_tmp_env,
-    babl_html_dump
-  ],
-  capture: true,
-)
-
-index_html = custom_target('index.html',
-  input : [
-    index_static_html,
-    join_paths(meson.source_root(), 'AUTHORS'),
-    join_paths(meson.source_root(), 'TODO'),
-    join_paths(meson.source_root(), 'NEWS'),
-    'toc',
-  ],
-  output: [ 'index.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'AUTHORS',  '@INPUT1@',
-    '&&', xml_insert, '@OUTPUT@', 'TODO',     '@INPUT2@',
-    '&&', xml_insert, '@OUTPUT@', 'NEWS',     '@INPUT3@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC',     '@INPUT4@',
-  ],
-  build_by_default: true,
-)
-
-Reference_html = custom_target('Reference.html',
-  input : [
-    'Reference-static.html',
-    'toc',
-    index_html_tmp,
-  ],
-  output: [ 'Reference.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC', '@INPUT1@',
-    '&&', xml_insert, '@OUTPUT@', 'BablBase', '@INPUT2@',
-  ],
-  build_by_default: true,
-)
-
-
-CMYK_html = custom_target('CMYK.html',
-  input : [
-    'CMYK-static.html',
-    'toc',
-  ],
-  output: [ 'CMYK.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC', '@INPUT1@',
-  ],
-  build_by_default: true,
-)
-
-OldNews_html = custom_target('OldNews.html',
-  input : [
-    'OldNews-static.html',
-    'toc',
-  ],
-  output: [ 'OldNews.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC', '@INPUT1@',
-  ],
-  build_by_default: true,
-)
-
-
-
-Glossary_html = custom_target('Glossary.html',
-  input : [
-    'Glossary-static.html',
-    'toc',
-  ],
-  output: [ 'Glossary.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC', '@INPUT1@',
-  ],
-  build_by_default: true,
-)
+# Don't build babl ref if cannot run compiled objects in this env
+if env_bin.found() and cc_can_run # and not meson.is_cross_build()
+  index_html_tmp = custom_target('index.html.tmp',
+    input : [ babl_html_dump, ],
+    output: [ 'index.html.tmp', ],
+    command: [
+      env_bin,
+      index_html_tmp_env,
+      babl_html_dump
+    ],
+    capture: true,
+  )
+else
+  warning('Cannot create babl reference in this environment')
+  index_html_tmp = 'index.html.tmp'
+endif
+
+TOC = files('toc')
+html_files = {
+  'index': [index_static_html, [
+    ['AUTHORS', files(meson.source_root() / 'AUTHORS')],
+    ['TODO',    files(meson.source_root() / 'TODO')],
+    ['NEWS',    files(meson.source_root() / 'NEWS')],
+    ['TOC',     TOC],
+  ]],
+  'Reference': ['auto', [
+    ['BablBase', index_html_tmp],
+    ['TOC',      TOC],
+  ]],
+  'CMYK': ['auto', [
+    ['TOC', TOC]
+  ]],
+  'OldNews': ['auto', [
+    ['TOC', TOC],
+  ]],
+  'Glossary': ['auto', [
+    ['TOC', TOC],
+  ]],
+  'ColorManagement': ['auto', [
+    ['TOC', TOC],
+  ]],
+  'UnifiedAlpha': ['auto', [
+    ['TOC', TOC],
+  ]],
+}
+
+foreach _file, _parms : html_files
+  if '@0@'.format(_parms[0]) == 'auto'
+    _in = '@0 -static html'.format(_file)
+  else
+    _in = _parms[0]
+  endif
+  _out = '@0@.html'.format(_file)
+
+  inserts = []
+  foreach _parm : _parms[1]
+    inserts += ['--insert', _parm[0], _parm[1]]
+  endforeach
+
+  _tgt = custom_target(_out,
+    input: _in,
+    output: _out,
+    command: [
+      xml_insert,
+      '--output' , '@OUTPUT@',
+      inserts,
+      '@INPUT@',
+    ],
+    build_by_default: true
+  )
+  if _file == 'index'
+    index_html = _tgt
+  endif
+endforeach
 
 
-ColorManagement_html = custom_target('ColorManagement.html',
-  input : [
-    'ColorManagement-static.html',
-    'toc',
-  ],
-  output: [ 'ColorManagement.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC',     '@INPUT1@',
-  ],
-  build_by_default: true,
-)
-
-UnifiedAlpha_html = custom_target('UnifiedAlpha.html',
-  input : [
-    'UnifiedAlpha-static.html',
-    'toc',
-  ],
-  output: [ 'UnifiedAlpha.html', ],
-  command: [
-    env_bin,
-    'cp', '@INPUT0@', '@OUTPUT@',
-    '&&', xml_insert, '@OUTPUT@', 'TOC',     '@INPUT1@',
-  ],
-  build_by_default: true,
-)
-
 run_target('push_web',
   command: [
     'scp', index_html, index_static_html, babl_css, scptarget,
diff --git a/meson.build b/meson.build
index a66bd96cf..85fd6c3fb 100644
--- a/meson.build
+++ b/meson.build
@@ -342,14 +342,22 @@ w3m_bin = find_program('w3m', required: false, native: true)
 ################################################################################
 # Build flags
 
-build_docs = false
-
-if get_option('with-docs')
-  if cc_can_run and env_bin.found() and not platform_win32
-    build_docs = true
-  else
-    warning('Unable to generate docs in this environment')
+# Docs - don't build by default in cross-build environments
+#        can't build if no env binary
+build_docs = true
+build_docs_msg = ''
+if get_option('with-docs') != 'false' and not env_bin.found()
+  build_docs = false
+  build_docs_msg = '(env program not available)'
+  warning('env is required to build documentation')
+elif get_option('with-docs') == 'auto'
+  if meson.is_cross_build()
+    build_docs = false
+    build_docs_msg = '(configure with -Ddocs=true to cross-build docs)'
   endif
+elif get_option('with-docs') == 'false'
+  build_docs = false
+  build_docs_msg = '(disabled)'
 endif
 
 
@@ -376,6 +384,7 @@ if build_docs
   subdir('docs')
 endif
 
+# Create README file from web page
 if w3m_bin.found() and build_docs
   custom_target('README',
     input: index_html,
@@ -387,6 +396,7 @@ if w3m_bin.found() and build_docs
       '@INPUT@',
     ],
     capture: true,
+    build_by_default: true
   )
 endif
 
diff --git a/meson_options.txt b/meson_options.txt
index 2bc57f600..442eb6563 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -1,7 +1,7 @@
 # Optional features
 option('with-docs',
-  type: 'boolean',
-  value: 'true', 
+  type: 'combo',
+  choices: ['auto', 'true', 'false'],
   description: 'build documentation'
 )
 option('enable-gir',
diff --git a/tools/xml-insert.py b/tools/xml-insert.py
new file mode 100644
index 000000000..cbe63dc4e
--- /dev/null
+++ b/tools/xml-insert.py
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+#
+# Utility script to insert an xml snippet into an existing document
+# 
+# Re-implements xml_insert.sh in python with extra options to send the 
+# output to a new file.
+# 
+# Copyright John Marshall 2020
+#
+
+from __future__ import print_function
+
+import os
+import sys
+import argparse
+
+class Args():
+    def __init__(self):
+        parser = argparse.ArgumentParser()
+        parser.add_argument(
+            '--output',
+            metavar='OUTPUT_FILE',
+            help='output file - otherwise output to STDOUT'
+        )
+        parser.add_argument(
+            '--insert',
+            action='append',
+            nargs=2,
+            required=True,
+            metavar=('TAG', 'INSERT_FILE'),
+            help='insert file tag and file name'
+        )
+        parser.add_argument(
+            'FILE',
+            metavar='INPUT_FILE',
+            help='input file'
+        )
+
+        self.input = os.path.realpath(parser.parse_args().FILE)
+        if parser.parse_args().output:
+            self.output = os.path.realpath(parser.parse_args().output)
+        else:
+            self.output = None
+        self.inserts = parser.parse_args().insert
+
+
+def main():
+    args = Args()
+
+    try:
+        in_file = open(args.input, 'r')
+    except IOError:
+        print('cannot access input file ' + args.input, 
+              file=sys.stderr)
+        sys.exit(1)
+
+    doc = in_file.read().splitlines()
+    in_file.close()
+
+    # get insert files
+    inserts = args.inserts
+    for insert in inserts:
+        ins_tag = '<!--' + insert[0] + '-->'
+
+        # find tag instances in input file
+        indices = []
+        for i, line in enumerate(doc):
+            if ins_tag in line:
+                indices.append(i)
+
+        if not indices:
+            print(ins_tag + ' not in input file - skipping',
+                  file=sys.stderr)
+            continue
+
+        # read in insert file
+        try:
+            ins_file = open(os.path.realpath(insert[1]), 'r')
+        except IOError:
+            print ('cannot open insert file %s - skipping' % insert[1],
+                  file=sys.stderr)
+            continue
+
+        if ins_file:
+            ins_doc = ins_file.read().splitlines()
+            ins_file.close()
+
+        # insert in reverse order so that remaining inert positions 
+        # remain valid
+        for index in reversed(indices):
+            doc[index+1:index+1] = ins_doc
+
+    # output to file or stdout
+    if args.output:
+        try:
+            out_file = open(os.path.realpath(args.output), 'w')
+        except IOError:
+            print('cannot open output file %s' % args.output)
+            sys.exit(1)
+    else:
+        out_file = sys.stdout
+
+    for line in doc:
+        print(line, file=out_file)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+  main()
\ No newline at end of file