untracked/build_scripts/doc-reference.py

   1 #!/usr/bin/env python3
   2
   3 # External command, intended to be called with run_command(), custom_target(),
   4 # meson.add_install_script() or meson.add_dist_script() in meson.build.
   5
   6 #                     argv[1]      argv[2]     argv[3:]
   7 # doc-reference.py <subcommand> <MMDOCTOOLDIR> <xxx>...
   8
   9 # <MMDOCTOOLDIR> is an absolute path in the source directory.
  10
  11 import os
  12 import sys
  13 import subprocess
  14 import shutil
  15
  16 subcommand = sys.argv[1]
  17 MMDOCTOOLDIR = sys.argv[2]
  18
  19 # Invoked from custom_target() in meson.build.
  20 def doxygen():
  21   #    argv[3]         argv[4:]
  22   # <doxytagfile> <doc_input_files>...
  23
  24   # <doxytagfile> is a relative or absolute path in the build directory.
  25   # <doc_input_files> are absolute paths in the source or build directory.
  26   doxytagfile = sys.argv[3]
  27   doc_outdir = os.path.dirname(doxytagfile)
  28
  29   # Search for doc_postprocess.py first in MMDOCTOOLDIR.
  30   sys.path.insert(0, MMDOCTOOLDIR)
  31   from doc_postprocess import doc_postprocess
  32
  33   # Export this variable for use in the Doxygen configuration file.
  34   child_env = os.environ.copy()
  35   child_env['MMDOCTOOLDIR'] = MMDOCTOOLDIR
  36
  37   # Remove old files.
  38   if os.path.isfile(doxytagfile):
  39     os.remove(doxytagfile)
  40   shutil.rmtree(os.path.join(doc_outdir, 'html'), ignore_errors=True)
  41
  42   # Relative paths in Doxyfile assume that Doxygen is run from the
  43   # build directory one level above Doxyfile.
  44   doxygen_cwd = os.path.join(doc_outdir, '..')
  45
  46   DOXYGEN = child_env.get('DOXYGEN', None)
  47   if not DOXYGEN:
  48     DOXYGEN = 'doxygen'
  49   doxygen_input = '@INCLUDE = ' + os.path.join('reference', 'Doxyfile') + '\n' \
  50                 + 'INPUT = "' + '" "'.join(sys.argv[4:]) + '"\n'
  51   # (Starting with Python 3.7 text=True is a more understandable equivalent to
  52   # universal_newlines=True. Let's use only features in Python 3.5.)
  53   result = subprocess.run([DOXYGEN, '-'], input=doxygen_input,
  54     universal_newlines=True, env=child_env, cwd=doxygen_cwd)
  55   if result.returncode:
  56     return result.returncode
  57
  58   return doc_postprocess(os.path.join(doc_outdir, 'html', '*.html'))
  59
  60 # Invoked from custom_target() in meson.build.
  61 def devhelp():
  62   #    argv[3]       argv[4]       argv[5]     argv[6]
  63   # <doxytagfile> <devhelpfile> <book_name> <book_title>
  64
  65   # <doxytagfile> and <devhelpfile> are relative or absolute paths in the build directory.
  66   doxytagfile = sys.argv[3]
  67   devhelpfile = sys.argv[4]
  68   book_name = sys.argv[5]
  69   book_title = sys.argv[6]
  70   tagfile_to_devhelp = os.path.join(MMDOCTOOLDIR, 'tagfile-to-devhelp2.xsl')
  71
  72   # The parameters to the Doxygen-to-Devhelp XSLT script.
  73   cmd = [
  74     'xsltproc',
  75     '--stringparam', 'book_title', book_title,
  76     '--stringparam', 'book_name', book_name,
  77     '--stringparam', 'book_base', 'html',
  78     '-o', devhelpfile,
  79     tagfile_to_devhelp,
  80     doxytagfile,
  81   ]
  82   return subprocess.run(cmd).returncode
  83
  84 # Invoked from meson.add_install_script().
  85 def install_doc():
  86   #    argv[3]       argv[4]      argv[5]        argv[6:]
  87   # <devhelpfile> <devhelpdir> <htmlrefdir> <docinstall_flags>...
  88
  89   # <devhelpfile> is a relative or absolute path in the build directory.
  90   # <htmlrefdir> and <devhelpdir> are installation directories, relative to {prefix}.
  91   devhelpfile = sys.argv[3]
  92   destdir_devhelpdir = os.path.join(os.getenv('MESON_INSTALL_DESTDIR_PREFIX'), sys.argv[4])
  93   destdir_htmlrefdir = os.path.join(os.getenv('MESON_INSTALL_DESTDIR_PREFIX'), sys.argv[5])
  94   prefix_htmlrefdir = os.path.join(os.getenv('MESON_INSTALL_PREFIX'), sys.argv[5])
  95   build_dir = os.path.dirname(devhelpfile)
  96
  97   # Search for doc_install.py first in MMDOCTOOLDIR.
  98   sys.path.insert(0, MMDOCTOOLDIR)
  99   from doc_install import doc_install_cmdargs, doc_install_funcargs
 100
 101   # Create the installation directories, if they do not exist.
 102   os.makedirs(destdir_htmlrefdir, exist_ok=True)
 103   os.makedirs(destdir_devhelpdir, exist_ok=True)
 104
 105   verbose = []
 106   if not os.getenv('MESON_INSTALL_QUIET'):
 107     verbose = ['--verbose']
 108
 109   # Install html files.
 110   cmdargs = [
 111     '--mode=0o644',
 112   ] + verbose + sys.argv[6:] + [
 113     '-t', destdir_htmlrefdir,
 114     '--glob',
 115     '--',
 116     os.path.join(build_dir, 'html', '*'),
 117   ]
 118   result1 = doc_install_cmdargs(cmdargs)
 119
 120   # Install the Devhelp file.
 121   # rstrip('/') means remove trailing /, if any.
 122   result2 = doc_install_funcargs(
 123     sources=[devhelpfile],
 124     target=destdir_devhelpdir,
 125     target_is_dir=True,
 126     mode=0o644,
 127     verbose=bool(verbose),
 128     book_base=prefix_htmlrefdir.rstrip('/'),
 129   )
 130
 131   return max(result1, result2)
 132
 133 # Invoked from meson.add_dist_script().
 134 def dist_doc():
 135   #      argv[3]              argv[4]       argv[5]     argv[6]
 136   # <doctool_dist_dir> <doc_ref_build_dir> <tagfile> <devhelpfile>
 137
 138   # <doctool_dist_dir> is a distribution directory, relative to MESON_PROJECT_DIST_ROOT.
 139   # <doc_ref_build_dir> is a relative or absolute path in the build directory.
 140   # <tagfile> and <devhelpfile> are relative or absolute paths in the build directory.
 141
 142   # MESON_PROJECT_DIST_ROOT is set only if meson.version() >= 0.58.0.
 143   project_dist_root = os.getenv('MESON_PROJECT_DIST_ROOT', os.getenv('MESON_DIST_ROOT'))
 144   doctool_dist_dir = os.path.join(project_dist_root, sys.argv[3])
 145   doc_ref_build_dir = sys.argv[4]
 146   tagfile = sys.argv[5]
 147   devhelpfile = sys.argv[6]
 148
 149   # Create the distribution directory, if it does not exist.
 150   os.makedirs(os.path.join(doctool_dist_dir, 'reference'), exist_ok=True)
 151
 152   # Distribute files that mm-common-get has copied to MMDOCTOOLDIR.
 153   # shutil.copy() does not copy timestamps.
 154   for file in ['doc_install.py', 'doc_postprocess.py', 'doxygen-extra.css', 'tagfile-to-devhelp2.xsl']:
 155     shutil.copy(os.path.join(MMDOCTOOLDIR, file), doctool_dist_dir)
 156
 157   # Distribute built files: tag file, devhelp file, html files.
 158   for file in [tagfile, devhelpfile]:
 159     shutil.copy(file, os.path.join(doctool_dist_dir, 'reference'))
 160   shutil.copytree(os.path.join(doc_ref_build_dir, 'html'),
 161                   os.path.join(doctool_dist_dir, 'reference', 'html'),
 162                   copy_function=shutil.copy)
 163   return 0
 164
 165 # Invoked from run_command() in meson.build.
 166 def get_script_property():
 167   #  argv[3]
 168   # <property>
 169   # argv[2] (MMDOCTOOLDIR) is not used.
 170   prop = sys.argv[3]
 171   if prop == 'requires_perl':
 172     print('false', end='') # stdout can be read in the meson.build file.
 173     return 0
 174   print(sys.argv[0], ': unknown property,', prop)
 175   return 1
 176
 177 # ----- Main -----
 178 if subcommand == 'doxygen':
 179   sys.exit(doxygen())
 180 if subcommand == 'devhelp':
 181   sys.exit(devhelp())
 182 if subcommand == 'install_doc':
 183   sys.exit(install_doc())
 184 if subcommand == 'dist_doc':
 185   sys.exit(dist_doc())
 186 if subcommand == 'get_script_property':
 187   sys.exit(get_script_property())
 188 print(sys.argv[0], ': illegal subcommand,', subcommand)
 189 sys.exit(1)