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.
6 # argv[1] argv[2] argv[3:]
7 # doc-reference.py <subcommand> <MMDOCTOOLDIR> <xxx>...
9 # <MMDOCTOOLDIR> is an absolute path in the source directory.
16 subcommand = sys.argv[1]
17 MMDOCTOOLDIR = sys.argv[2]
19 # Invoked from custom_target() in meson.build.
22 # <doxytagfile> <doc_input_files>...
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)
29 # Search for doc_postprocess.py first in MMDOCTOOLDIR.
30 sys.path.insert(0, MMDOCTOOLDIR)
31 from doc_postprocess import doc_postprocess
33 # Export this variable for use in the Doxygen configuration file.
34 child_env = os.environ.copy()
35 child_env['MMDOCTOOLDIR'] = MMDOCTOOLDIR
38 if os.path.isfile(doxytagfile):
39 os.remove(doxytagfile)
40 shutil.rmtree(os.path.join(doc_outdir, 'html'), ignore_errors=True)
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, '..')
46 DOXYGEN = child_env.get('DOXYGEN', None)
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)
56 return result.returncode
58 return doc_postprocess(os.path.join(doc_outdir, 'html', '*.html'))
60 # Invoked from custom_target() in meson.build.
62 # argv[3] argv[4] argv[5] argv[6]
63 # <doxytagfile> <devhelpfile> <book_name> <book_title>
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')
72 # The parameters to the Doxygen-to-Devhelp XSLT script.
75 '--stringparam', 'book_title', book_title,
76 '--stringparam', 'book_name', book_name,
77 '--stringparam', 'book_base', 'html',
82 return subprocess.run(cmd).returncode
84 # Invoked from meson.add_install_script().
86 # argv[3] argv[4] argv[5] argv[6:]
87 # <devhelpfile> <devhelpdir> <htmlrefdir> <docinstall_flags>...
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)
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
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)
106 if not os.getenv('MESON_INSTALL_QUIET'):
107 verbose = ['--verbose']
109 # Install html files.
112 ] + verbose + sys.argv[6:] + [
113 '-t', destdir_htmlrefdir,
116 os.path.join(build_dir, 'html', '*'),
118 result1 = doc_install_cmdargs(cmdargs)
120 # Install the Devhelp file.
121 # rstrip('/') means remove trailing /, if any.
122 result2 = doc_install_funcargs(
123 sources=[devhelpfile],
124 target=destdir_devhelpdir,
127 verbose=bool(verbose),
128 book_base=prefix_htmlrefdir.rstrip('/'),
131 return max(result1, result2)
133 # Invoked from meson.add_dist_script().
135 # argv[3] argv[4] argv[5] argv[6]
136 # <doctool_dist_dir> <doc_ref_build_dir> <tagfile> <devhelpfile>
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.
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]
149 # Create the distribution directory, if it does not exist.
150 os.makedirs(os.path.join(doctool_dist_dir, 'reference'), exist_ok=True)
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)
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)
165 # Invoked from run_command() in meson.build.
166 def get_script_property():
169 # argv[2] (MMDOCTOOLDIR) is not used.
171 if prop == 'requires_perl':
172 print('false', end='') # stdout can be read in the meson.build file.
174 print(sys.argv[0], ': unknown property,', prop)
178 if subcommand == 'doxygen':
180 if subcommand == 'devhelp':
182 if subcommand == 'install_doc':
183 sys.exit(install_doc())
184 if subcommand == 'dist_doc':
186 if subcommand == 'get_script_property':
187 sys.exit(get_script_property())
188 print(sys.argv[0], ': illegal subcommand,', subcommand)