tools/tutorial-custom-cmd.py

   1 #!/usr/bin/env python3
   2
   3 # External command, intended to be called with custom_target() in meson.build
   4
   5 #                           argv[1]   argv[2:]
   6 # tutorial-custom-cmd.py <subcommand> <xxx>...
   7
   8 import os
   9 import sys
  10 import subprocess
  11 import shutil
  12
  13 subcommand = sys.argv[1]
  14
  15 def html():
  16   #      argv[2]          argv[3]
  17   # <input_xml_file> <output_html_dir>
  18
  19   input_xml_file = sys.argv[2]
  20   output_html_dir = sys.argv[3]
  21
  22   # Set the use.id.as.filename param so that we don't use the chapter / section
  23   # number as the filename, otherwise the url will change every time anything is
  24   # re-ordered or inserted in the documentation.
  25   # For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/html/
  26   xslt_params = [
  27     '--param', 'toc.section.depth', '1',
  28     '--stringparam', 'chunker.output.indent', 'yes',
  29     '--stringparam', 'chunker.output.encoding', 'UTF-8',
  30     '--stringparam', 'toc.list.type', 'ul',
  31     '--param', 'use.id.as.filename', '1',
  32   ]
  33
  34   # The recommended stylesheet for DocBook V5.0 is .../xsl-ns/...
  35   # It's not used here because the docbook-xsl-ns package is not available
  36   # when building with gnome-build-meta.
  37   xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl'
  38
  39   # Remove old files and create the destination directory.
  40   shutil.rmtree(output_html_dir, ignore_errors=True)
  41   os.makedirs(output_html_dir, exist_ok=True)
  42
  43   cmd = [
  44     'xsltproc',
  45   ] + xslt_params + [
  46     '-o', output_html_dir + '/',
  47     '--xinclude',
  48     xslt_stylesheet,
  49     input_xml_file,
  50   ]
  51   result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
  52                           universal_newlines=True)
  53   # xsltproc prints the names of all written files. Don't print those lines.
  54   for line in result.stdout.splitlines():
  55     if not line.startswith('Writing '):
  56       print(line)
  57
  58   return result.returncode
  59
  60 def xmllint():
  61   from pathlib import Path
  62
  63   #  argv[2]       argv[3]          argv[4]
  64   # <validate> <input_xml_file> <stamp_file_path>
  65
  66   validate = sys.argv[2]
  67   input_xml_file = sys.argv[3]
  68   stamp_file_path = sys.argv[4]
  69
  70   relax_ng_schema = 'http://docbook.org/xml/5.0/rng/docbook.rng'
  71   # schematron_schema = 'http://docbook.org/xml/5.0/sch/docbook.sch'
  72
  73   # Validation against the Schematron schema does not work on Ubuntu 21.04:
  74   # file:///usr/share/xml/docbook/schema/schematron/5.0/docbook.sch:6: element rule:
  75   #   Schemas parser error : Failed to compile context expression db:firstterm[@linkend]
  76   # .....
  77   # Schematron schema http://docbook.org/xml/5.0/sch/docbook.sch failed to compile
  78
  79   cmd = [
  80     'xmllint',
  81     '--noout',
  82     '--noent',
  83     '--xinclude',
  84   ]
  85   if validate == 'true':
  86     cmd += [
  87       '--relaxng', relax_ng_schema,
  88       #'--schematron', schematron_schema,
  89     ]
  90   cmd += [input_xml_file]
  91   result = subprocess.run(cmd)
  92   if result.returncode:
  93     return result.returncode
  94
  95   Path(stamp_file_path).touch(exist_ok=True)
  96   return 0
  97
  98 # dblatex and xsltproc+fop generate a PDF file.
  99 # docbook2pdf can generate PDF files from DocBook4 files, but not from DocBook5 files.
 100 # xsltproc+xmlroff (version 0.6.3) does not seem to work acceptably.
 101 def dblatex():
 102   #      argv[2]         argv[3]
 103   # <input_xml_file> <output_pdf_file>
 104   # Create a PDF file, using dblatex.
 105
 106   input_xml_file = sys.argv[2]
 107   output_pdf_file = sys.argv[3]
 108
 109   # For a list of available parameters, see http://dblatex.sourceforge.net/doc/manual/
 110   dblatex_params = [
 111     '-P', 'toc.section.depth=1',
 112     '-P', 'paper.type=a4paper',
 113     '-P', 'doc.collab.show=1',
 114     '-P', 'latex.output.revhistory=0',
 115   ]
 116
 117   cmd = [
 118     'dblatex',
 119   ] + dblatex_params + [
 120     '-o', output_pdf_file,
 121     '--pdf',
 122     input_xml_file,
 123   ]
 124   return subprocess.run(cmd).returncode
 125
 126 def fop():
 127   #      argv[2]         argv[3]
 128   # <input_xml_file> <output_pdf_file>
 129   # Create a PDF file, using fop.
 130
 131   input_xml_file = sys.argv[2]
 132   output_pdf_file = sys.argv[3]
 133
 134   fo_file = os.path.splitext(output_pdf_file)[0] + '.fo'
 135
 136   # For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/fo/
 137   # For a list of available paper types, see the description of the page.width.portrait parameter.
 138   xslt_params = [
 139     '--param', 'toc.section.depth', '1',
 140     '--stringparam', 'fop1.extensions', '1',
 141     '--stringparam', 'page.orientation', 'portrait',
 142     '--stringparam', 'paper.type', 'A4',
 143   ]
 144
 145   xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl'
 146
 147   # Generate a .fo (formatting object) file.
 148   # fop can take an xslt stylesheet parameter, but it can only read local files.
 149   # xsltproc is necessary if you want to read the stylesheet from the internet.
 150   cmd = [
 151     'xsltproc',
 152   ] + xslt_params + [
 153     '-o', fo_file,
 154     '--xinclude',
 155     xslt_stylesheet,
 156     input_xml_file,
 157   ]
 158   result = subprocess.run(cmd)
 159   if result.returncode:
 160     return result.returncode
 161
 162   cmd = [
 163     'fop',
 164     '-fo', fo_file,
 165     '-pdf', output_pdf_file,
 166   ]
 167   return subprocess.run(cmd).returncode
 168
 169 # Invoked from meson.add_dist_script().
 170 def dist_doc():
 171   #    argv[2]        argv[3]        argv[4]    argv[5]
 172   # <doc_dist_dir> <doc_build_dir> <xml_file> <pdf_file>
 173
 174   # <doc_dist_dir> is a distribution directory, relative to MESON_PROJECT_DIST_ROOT.
 175   # <doc_build_dir> is a relative or absolute path in the build directory.
 176   # <xml_file> is a relative or absolute path in the source directory.
 177   # <pdf_file> is a relative or absolute path in the build directory.
 178
 179   # MESON_PROJECT_DIST_ROOT is set only if meson.version() >= 0.58.0.
 180   project_dist_root = os.getenv('MESON_PROJECT_DIST_ROOT', os.getenv('MESON_DIST_ROOT'))
 181   doc_dist_dir = os.path.join(project_dist_root, sys.argv[2])
 182   doc_build_dir = sys.argv[3]
 183   xml_file = sys.argv[4]
 184   pdf_file = sys.argv[5]
 185
 186   # Create the distribution directory, if it does not exist.
 187   os.makedirs(doc_dist_dir, exist_ok=True)
 188
 189   # Distribute built html files.
 190   shutil.copytree(os.path.join(doc_build_dir, 'html'),
 191                   os.path.join(doc_dist_dir, 'html'),
 192                   copy_function=shutil.copy)
 193
 194   # If there is an updated PDF file, distribute it.
 195   if os.path.isfile(pdf_file) and \
 196      os.stat(pdf_file).st_mtime > os.stat(xml_file).st_mtime:
 197     shutil.copy(pdf_file, doc_dist_dir)
 198   else:
 199     print('--- Info: No updated PDF file found.')
 200
 201   return 0
 202
 203 # ----- Main -----
 204 if subcommand == 'html':
 205   sys.exit(html())
 206 if subcommand == 'xmllint':
 207   sys.exit(xmllint())
 208 if subcommand == 'dblatex':
 209   sys.exit(dblatex())
 210 if subcommand == 'fop':
 211   sys.exit(fop())
 212 if subcommand == 'dist_doc':
 213   sys.exit(dist_doc())
 214 print(sys.argv[0], ': illegal subcommand,', subcommand)
 215 sys.exit(1)