[PATCH 0/2] docs: Fix migration.html generation and report such errors next time
Invert the order of the patches to see the error: FAILED: docs/migration.xslout.html /usr/bin/meson --internal exe --capture docs/migration.xslout.html -- /bin/xsltproc --stringparam pagesrc docs/migration.html.in --stringparam builddir /home/pipo/build/libvirt/gcc --stringparam timestamp 'Mon Oct 12 14:03:50 2020 UTC' --nonet ../../../libvirt/docs/site.xsl ../../../libvirt/docs/migration.html.in ../../../libvirt/docs/migration.html.in:664: parser error : Opening and ending tag mismatch: p line 649 and body </body> ^ ../../../libvirt/docs/migration.html.in:665: parser error : Opening and ending tag mismatch: body line 649 and html </html> ^ ../../../libvirt/docs/migration.html.in:666: parser error : EndTag: '</' not found ^ unable to parse ../../../libvirt/docs/migration.html.in [132/262] Generating 'docs/ci.xslout.html.p/ci.html.in'. ninja: build stopped: subcommand failed. Peter Krempa (2): docs: migration: Fix syntax docs: meson.build: Generate HTML files directly by meson docs/meson.build | 39 +++++++++++++++++++++++++-------------- docs/migration.html.in | 1 + scripts/meson-html-gen.py | 37 ------------------------------------- 3 files changed, 26 insertions(+), 51 deletions(-) delete mode 100755 scripts/meson-html-gen.py -- 2.26.2
One of the paragraphs added in f51cbe92c0d was not terminated thus making it invalid XML/XHTML. This was not caught by the build system as 'scripts/meson-html-gen.py' unnecessarily obscures and hides errors from 'xsltproc'. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/migration.html.in | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migration.html.in b/docs/migration.html.in index 162c202227..dd5eddd6f4 100644 --- a/docs/migration.html.in +++ b/docs/migration.html.in @@ -653,6 +653,7 @@ virsh migrate --p2p --tunnelled web1 qemu+ssh://desthost/system qemu+ssh://10.0. daemons or forwarding connections to these sockets manually (using <code>socat</code>, <code>netcat</code> or a custom piece of software): + </p> <pre> virsh migrate web1 [--p2p] --copy-storage-all 'qemu+unix:///system?socket=/tmp/migdir/test-sock-driver' 'unix:///tmp/migdir/test-sock-qemu' --disks-uri unix:///tmp/migdir/test-sock-nbd </pre> -- 2.26.2
Our HTML file generation has two steps: 1) XSL transformation This applies headers/footers and various other bits. 2) xmllint reformat To fix indentation and to look like a proper XML/XHTML. Historically these were done in a pipeline. The meson conversion attempted to do the same by adding 'scripts/meson-html-gen.py' which tried to pipeline them. Unfortunately this hid errors from 'xsltproc' as return value was not checked and the stderr was piped into xmllints stdin. The result was that any invalid input file would result into an empty output file. Since the script's only purpose was to prevent additional temporary files being created at the cost of compexity and obscurity (by hiding the commands used to process the XMLs and their arguments being weirdly passed through positional arguments) we can remove it if we accept extra temporary files in the directory. Moving the generation directly into the meson definition makes it more obvious what's happening and saves readers from having to parse what's going on. A free bonus is that errors are now properly caught and reported. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 39 +++++++++++++++++++++++++-------------- scripts/meson-html-gen.py | 37 ------------------------------------- 2 files changed, 25 insertions(+), 51 deletions(-) delete mode 100755 scripts/meson-html-gen.py diff --git a/docs/meson.build b/docs/meson.build index 400c1ca955..d1943161b8 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -253,33 +253,44 @@ docs_html_in_gen += { } foreach data : docs_html_in_gen - html_file = '@0@.html'.format(data['name']) + xslout_filename = '@0@.xslout.html'.format(data['name']) + html_filename = '@0@.html'.format(data['name']) - out_file = custom_target( - html_file, + xslout_file = custom_target( + xslout_filename, input: data['file'], - output: html_file, + output: xslout_filename, command: [ - meson_python_prog, - python3_prog.path(), - meson_html_gen_prog.path(), xsltproc_prog.path(), - xmllint_prog.path(), - meson.build_root(), - docs_timestamp, + '--stringparam', 'pagesrc', data.get('source', ''), + '--stringparam', 'builddir', meson.build_root(), + '--stringparam', 'timestamp', docs_timestamp, + '--nonet', site_xsl, '@INPUT@', - '@OUTPUT@', - data.get('source', []), ], depends: [ aclperms_gen ], depend_files: [ page_xsl ], + capture: true, + ) + + html_file = custom_target( + html_filename, + input: xslout_file, + output: html_filename, + command: [ + xmllint_prog.path(), + '--nonet', + '--format', + '@INPUT@', + ], install: true, install_dir: docs_html_dir, + capture: true ) - install_web_deps += out_file - install_web_files += '@0@:@1@'.format(out_file.full_path(), docs_html_dir) + install_web_deps += html_file + install_web_files += '@0@:@1@'.format(html_file.full_path(), docs_html_dir) endforeach subdir('fonts') diff --git a/scripts/meson-html-gen.py b/scripts/meson-html-gen.py deleted file mode 100755 index 2731d734a7..0000000000 --- a/scripts/meson-html-gen.py +++ /dev/null @@ -1,37 +0,0 @@ -#!/usr/bin/env python3 - -import argparse -import subprocess - -parser = argparse.ArgumentParser() -parser.add_argument("xsltproc", type=str, help="path to xsltproc bin") -parser.add_argument("xmllint", type=str, help="path to xmllint bin") -parser.add_argument("builddir", type=str, help="build root dir path") -parser.add_argument("timestamp", type=str, help="docs timestamp") -parser.add_argument("style", type=str, help="XSL stile file") -parser.add_argument("infile", type=str, help="path to source HTML file") -parser.add_argument("htmlfile", type=str, help="path to generated HTML file") -parser.add_argument("pagesrc", type=str, default="", nargs='?', help="(optional) path to source file used for edit this page") -args = parser.parse_args() - -html_tmp = subprocess.run( - [ - args.xsltproc, - '--stringparam', 'pagesrc', args.pagesrc, - '--stringparam', 'builddir', args.builddir, - '--stringparam', 'timestamp', args.timestamp, - '--nonet', args.style, args.infile, - ], - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, -) - -html = subprocess.run( - [args.xmllint, '--nonet', '--format', '-'], - input=html_tmp.stdout, - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, -) - -with open(args.htmlfile, 'wb') as outfile: - outfile.write(html.stdout) -- 2.26.2
On Mon, Oct 12, 2020 at 16:28:35 +0200, Peter Krempa wrote:
Our HTML file generation has two steps:
1) XSL transformation
This applies headers/footers and various other bits.
2) xmllint reformat
To fix indentation and to look like a proper XML/XHTML.
Historically these were done in a pipeline. The meson conversion attempted to do the same by adding 'scripts/meson-html-gen.py' which tried to pipeline them.
Unfortunately this hid errors from 'xsltproc' as return value was not checked and the stderr was piped into xmllints stdin. The result was that any invalid input file would result into an empty output file.
Since the script's only purpose was to prevent additional temporary files being created at the cost of compexity and obscurity (by hiding the commands used to process the XMLs and their arguments being weirdly passed through positional arguments) we can remove it if we accept extra temporary files in the directory.
Moving the generation directly into the meson definition makes it more obvious what's happening and saves readers from having to parse what's going on. A free bonus is that errors are now properly caught and reported.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 39 +++++++++++++++++++++++++-------------- scripts/meson-html-gen.py | 37 -------------------------------------
Sigh. Self-NACK. I didn't commit the deletion of meson-html-gen.py when testing and didn't notice that we've copy-pasted the same pattern into subdirectories. So much for reusability :(
participants (1)
-
Peter Krempa