Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
---
 docs/Makefile.am                              | 120 -----------------
 docs/manpages/{index.rst => index.rst.in}     |   0
 .../{libvirtd.rst => libvirtd.rst.in}         |   0
 docs/manpages/meson.build                     | 126 ++++++++++++++++++
 docs/manpages/{virsh.rst => virsh.rst.in}     |   0
 .../{virt-admin.rst => virt-admin.rst.in}     |   0
 ...validate.rst => virt-host-validate.rst.in} |   0
 ...ogin-shell.rst => virt-login-shell.rst.in} |   0
 ...-validate.rst => virt-pki-validate.rst.in} |   0
 ...virt-qemu-run.rst => virt-qemu-run.rst.in} |   0
 ...leanup.rst => virt-sanlock-cleanup.rst.in} |   0
 ...-validate.rst => virt-xml-validate.rst.in} |   0
 .../{virtlockd.rst => virtlockd.rst.in}       |   0
 .../{virtlogd.rst => virtlogd.rst.in}         |   0
 docs/meson.build                              |   1 +
 15 files changed, 127 insertions(+), 120 deletions(-)
 rename docs/manpages/{index.rst => index.rst.in} (100%)
 rename docs/manpages/{libvirtd.rst => libvirtd.rst.in} (100%)
 create mode 100644 docs/manpages/meson.build
 rename docs/manpages/{virsh.rst => virsh.rst.in} (100%)
 rename docs/manpages/{virt-admin.rst => virt-admin.rst.in} (100%)
 rename docs/manpages/{virt-host-validate.rst => virt-host-validate.rst.in} (100%)
 rename docs/manpages/{virt-login-shell.rst => virt-login-shell.rst.in} (100%)
 rename docs/manpages/{virt-pki-validate.rst => virt-pki-validate.rst.in} (100%)
 rename docs/manpages/{virt-qemu-run.rst => virt-qemu-run.rst.in} (100%)
 rename docs/manpages/{virt-sanlock-cleanup.rst => virt-sanlock-cleanup.rst.in} (100%)
 rename docs/manpages/{virt-xml-validate.rst => virt-xml-validate.rst.in} (100%)
 rename docs/manpages/{virtlockd.rst => virtlockd.rst.in} (100%)
 rename docs/manpages/{virtlogd.rst => virtlogd.rst.in} (100%)

diff --git a/docs/Makefile.am b/docs/Makefile.am
index d17455f135e..8fe0959bc2d 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -16,129 +16,9 @@
 ## License along with this library.  If not, see
 ## <http://www.gnu.org/licenses/>.
 
-# Sync with src/util/
-KEYCODES = linux osx atset1 atset2 atset3 xtkbd usb win32 qnum
-KEYNAMES = linux osx win32
-
-manpages_rst = \
-  manpages/index.rst \
-  $(NULL)
-manpages1_rst = \
-  manpages/virt-pki-validate.rst \
-  manpages/virt-xml-validate.rst \
-  manpages/virt-admin.rst \
-  manpages/virsh.rst \
-  $(NULL)
-manpages7_rst = \
-  $(KEYCODES:%=manpages/virkeycode-%.rst) \
-  $(KEYNAMES:%=manpages/virkeyname-%.rst) \
-  $(NULL)
-manpages8_rst = $(NULL)
-manpages_rst += \
-  $(manpages1_rst) \
-  $(manpages7_rst) \
-  $(manpages8_rst) \
-  $(NULL)
-if WITH_LIBVIRTD
-manpages8_rst += \
-  manpages/libvirtd.rst \
-  manpages/virtlockd.rst \
-  manpages/virtlogd.rst \
-  $(NULL)
-else ! WITH_LIBVIRTD
-manpages_rst += \
-  manpages/libvirtd.rst \
-  manpages/virtlockd.rst \
-  manpages/virtlogd.rst \
-  $(NULL)
-endif ! WITH_LIBVIRTD
-if WITH_HOST_VALIDATE
-  manpages1_rst += manpages/virt-host-validate.rst
-else ! WITH_HOST_VALIDATE
-  manpages_rst += manpages/virt-host-validate.rst
-endif ! WITH_HOST_VALIDATE
-if WITH_LOGIN_SHELL
-  manpages1_rst += manpages/virt-login-shell.rst
-else ! WITH_LOGIN_SHELL
-  manpages_rst += manpages/virt-login-shell.rst
-endif ! WITH_LOGIN_SHELL
-if WITH_SANLOCK
-  manpages8_rst += manpages/virt-sanlock-cleanup.rst
-else ! WITH_SANLOCK
-  manpages_rst += manpages/virt-sanlock-cleanup.rst
-endif ! WITH_SANLOCK
-if WITH_QEMU
-  manpages1_rst += manpages/virt-qemu-run.rst
-else ! WITH_QEMU
-  manpages_rst += manpages/virt-qemu-run.rst
-endif ! WITH_QEMU
-manpages_rst_html_in = \
-  $(manpages_rst:%.rst=%.html.in)
-manpages_html = \
-  $(manpages_rst_html_in:%.html.in=%.html)
-
-man1_MANS = $(manpages1_rst:%.rst=%.1)
-man7_MANS = $(manpages7_rst:%.rst=%.7)
-man8_MANS = $(manpages8_rst:%.rst=%.8)
-
-%.1: %.rst
-	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
-	   grep -v '^\.\. contents::' < $< | \
-	   sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
-	       -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
-	   $(RST2MAN) --strict > $@ || { rm $@ && exit 1; }
-
-%.7: %.rst
-	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
-	   grep -v '^\.\. contents::' < $< | \
-	   sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
-	       -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
-	   $(RST2MAN) --strict > $@ || { rm $@ && exit 1; }
-
-%.8: %.rst
-	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
-	   grep -v '^\.\. contents::' < $< | \
-	   sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
-	       -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
-	   $(RST2MAN) --strict > $@ || { rm $@ && exit 1; }
-
-manpages/virkeycode-%.rst: $(top_srcdir)/src/keycodemapdb/data/keymaps.csv \
-		$(top_srcdir)/src/keycodemapdb/tools/keymap-gen Makefile.am
-	$(AM_V_GEN)export NAME=`echo $@ | \
-		sed -e 's,manpages/virkeycode-,,' -e 's,\.rst,,'` && \
-		$(MKDIR_P) manpages/ && \
-		$(RUNUTF8) $(PYTHON) $(top_srcdir)/src/keycodemapdb/tools/keymap-gen \
-		code-docs \
-		--lang rst \
-		--title "virkeycode-$$NAME" \
-		--subtitle "Key code values for $$NAME" \
-		$(top_srcdir)/src/keycodemapdb/data/keymaps.csv $$NAME > $@
-
-manpages/virkeyname-%.rst: $(top_srcdir)/src/keycodemapdb/data/keymaps.csv \
-		$(top_srcdir)/src/keycodemapdb/tools/keymap-gen Makefile.am
-	$(AM_V_GEN)export NAME=`echo $@ | \
-		sed -e 's,manpages/virkeyname-,,' -e 's,\.rst,,'` && \
-		$(MKDIR_P) manpages/ && \
-		$(RUNUTF8) $(PYTHON) $(top_srcdir)/src/keycodemapdb/tools/keymap-gen \
-		name-docs \
-		--lang rst \
-		--title "virkeyname-$$NAME" \
-		--subtitle "Key name values for $$NAME" \
-		$(top_srcdir)/src/keycodemapdb/data/keymaps.csv $$NAME > $@
-
-manpagesdir = $(HTML_DIR)/manpages
-manpages_DATA = $(manpages_html)
-
 schemadir = $(pkgdatadir)/schemas
 schema_DATA = $(wildcard $(srcdir)/schemas/*.rng)
 
-manpages/%.html.in: manpages/%.rst
-	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
-	 grep -v '^:Manual ' < $< | \
-	  sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
-	     -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
-	  $(RST2HTML) --strict > $@ || { rm $@ && exit 1; }
-
 check-html:
 	$(XMLLINT) --nonet --noout html/*.html
 
diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst.in
similarity index 100%
rename from docs/manpages/index.rst
rename to docs/manpages/index.rst.in
diff --git a/docs/manpages/libvirtd.rst b/docs/manpages/libvirtd.rst.in
similarity index 100%
rename from docs/manpages/libvirtd.rst
rename to docs/manpages/libvirtd.rst.in
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
new file mode 100644
index 00000000000..72d362e92d8
--- /dev/null
+++ b/docs/manpages/meson.build
@@ -0,0 +1,126 @@
+# docs_man_files
+#   each entry is a dictionary with following items:
+#   name - man page name (required)
+#   section - man page section (required)
+#   install - whether to build and install the man page (required)
+#   file - generated RST file (optional, default none)
+
+docs_man_files = [
+  { 'name': 'index', 'section': '', 'install': false },
+
+  { 'name': 'virsh', 'section': '1', 'install': true },
+  { 'name': 'virt-admin', 'section': '1', 'install': true },
+  { 'name': 'virt-host-validate', 'section': '1', 'install': conf.has('WITH_HOST_VALIDATE') },
+  { 'name': 'virt-login-shell', 'section': '1', 'install': conf.has('WITH_LOGIN_SHELL') },
+  { 'name': 'virt-pki-validate', 'section': '1', 'install': true },
+  { 'name': 'virt-qemu-run', 'section': '1', 'install': conf.has('WITH_QEMU') },
+  { 'name': 'virt-xml-validate', 'section': '1', 'install': true },
+
+  { 'name': 'libvirtd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
+  { 'name': 'virt-sanlock-cleanup', 'section': '8', 'install': sanlock_dep.found() },
+  { 'name': 'virtlockd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
+  { 'name': 'virtlogd', 'section': '8', 'install': conf.has('WITH_LIBVIRTD') },
+]
+
+foreach name : keycode_list
+  rst_file = custom_target(
+    'virkeycode-@0@.rst'.format(name),
+    input: keymap_src_file,
+    output: 'virkeycode-@0@.rst'.format(name),
+    command: [
+      meson_python_prog, python3_prog, keymap_gen_prog, 'code-docs',
+      '--lang', 'rst',
+      '--title', 'virkeycode-@0@'.format(name),
+      '--subtitle', 'Key code values for @0@'.format(name),
+      '@INPUT@', name,
+    ],
+    capture: true,
+    build_by_default: true,
+  )
+
+  docs_man_files += {
+    'name': 'virkeycode-@0@'.format(name), 'section': '7', 'install': true, 'file': rst_file,
+  }
+endforeach
+
+foreach name : keyname_list
+  rst_file = custom_target(
+    'virkeyname-@0@.rst'.format(name),
+    input: keymap_src_file,
+    output: 'virkeyname-@0@.rst'.format(name),
+    command: [
+      meson_python_prog, python3_prog, keymap_gen_prog, 'name-docs',
+      '--lang', 'rst',
+      '--title', 'virkeyname-@0@'.format(name),
+      '--subtitle', 'Key name values for @0@'.format(name),
+      '@INPUT@', name,
+    ],
+    capture: true,
+    build_by_default: true,
+  )
+
+  docs_man_files += {
+    'name': 'virkeyname-@0@'.format(name), 'section': '7', 'install': true, 'file': rst_file,
+  }
+endforeach
+
+docs_man_conf = configuration_data()
+docs_man_conf.set('SYSCONFDIR', sysconfdir)
+docs_man_conf.set('RUNSTATEDIR', runstatedir)
+
+foreach data : docs_man_files
+  rst_in_file = '@0@.rst.in'.format(data['name'])
+  html_in_file = '@0@.html.in'.format(data['name'])
+  html_file = '@0@.html'.format(data['name'])
+
+  if data.has_key('file')
+    rst_file = data['file']
+  else
+    rst_file = configure_file(
+      input: rst_in_file,
+      output: '@0@.rst'.format(data['name']),
+      configuration: docs_man_conf,
+    )
+  endif
+
+  if data['install']
+    man_file = '@0@.@1@'.format(data['name'], data['section'])
+    man_page = custom_target(
+      man_file,
+      input: rst_file,
+      output: man_file,
+      command: [ rst2man_prog, '--strict', '@INPUT@', '@OUTPUT@' ],
+      install: true,
+      install_dir: mandir / 'man@0@'.format(data['section']),
+    )
+  endif
+
+  html_in = custom_target(
+    html_in_file,
+    input: rst_file,
+    output: html_in_file,
+    command: [ rst2html_prog, '--strict', '@INPUT@' ],
+    capture: true,
+  )
+
+  custom_target(
+    html_file,
+    input: html_in,
+    output: html_file,
+    command: [
+      meson_python_prog,
+      meson_html_gen_prog,
+      xsltproc_prog.path(),
+      xmllint_prog.path(),
+      meson.build_root(),
+      docs_timestamp,
+      site_xsl,
+      '@INPUT@',
+      '@OUTPUT@',
+    ],
+    depends: [ aclperms_gen ],
+    depend_files: [ page_xsl ],
+    install: true,
+    install_dir: docs_html_dir / 'manpages',
+  )
+endforeach
diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst.in
similarity index 100%
rename from docs/manpages/virsh.rst
rename to docs/manpages/virsh.rst.in
diff --git a/docs/manpages/virt-admin.rst b/docs/manpages/virt-admin.rst.in
similarity index 100%
rename from docs/manpages/virt-admin.rst
rename to docs/manpages/virt-admin.rst.in
diff --git a/docs/manpages/virt-host-validate.rst b/docs/manpages/virt-host-validate.rst.in
similarity index 100%
rename from docs/manpages/virt-host-validate.rst
rename to docs/manpages/virt-host-validate.rst.in
diff --git a/docs/manpages/virt-login-shell.rst b/docs/manpages/virt-login-shell.rst.in
similarity index 100%
rename from docs/manpages/virt-login-shell.rst
rename to docs/manpages/virt-login-shell.rst.in
diff --git a/docs/manpages/virt-pki-validate.rst b/docs/manpages/virt-pki-validate.rst.in
similarity index 100%
rename from docs/manpages/virt-pki-validate.rst
rename to docs/manpages/virt-pki-validate.rst.in
diff --git a/docs/manpages/virt-qemu-run.rst b/docs/manpages/virt-qemu-run.rst.in
similarity index 100%
rename from docs/manpages/virt-qemu-run.rst
rename to docs/manpages/virt-qemu-run.rst.in
diff --git a/docs/manpages/virt-sanlock-cleanup.rst b/docs/manpages/virt-sanlock-cleanup.rst.in
similarity index 100%
rename from docs/manpages/virt-sanlock-cleanup.rst
rename to docs/manpages/virt-sanlock-cleanup.rst.in
diff --git a/docs/manpages/virt-xml-validate.rst b/docs/manpages/virt-xml-validate.rst.in
similarity index 100%
rename from docs/manpages/virt-xml-validate.rst
rename to docs/manpages/virt-xml-validate.rst.in
diff --git a/docs/manpages/virtlockd.rst b/docs/manpages/virtlockd.rst.in
similarity index 100%
rename from docs/manpages/virtlockd.rst
rename to docs/manpages/virtlockd.rst.in
diff --git a/docs/manpages/virtlogd.rst b/docs/manpages/virtlogd.rst.in
similarity index 100%
rename from docs/manpages/virtlogd.rst
rename to docs/manpages/virtlogd.rst.in
diff --git a/docs/meson.build b/docs/meson.build
index 17c8f956870..a03beb86b77 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -290,6 +290,7 @@ subdir('internals')
 subdir('js')
 subdir('kbase')
 subdir('logos')
+subdir('manpages')
 
 
 # This hack enables us to view the web pages
-- 
2.26.2

On Thu, Jul 16, 2020 at 11:59:31 +0200, Pavel Hrdina wrote:
> Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
> ---

[...]

> +foreach name : keyname_list
> +  rst_file = custom_target(
> +    'virkeyname-@0@.rst'.format(name),
> +    input: keymap_src_file,
> +    output: 'virkeyname-@0@.rst'.format(name),
> +    command: [
> +      meson_python_prog, python3_prog, keymap_gen_prog, 'name-docs',
> +      '--lang', 'rst',
> +      '--title', 'virkeyname-@0@'.format(name),
> +      '--subtitle', 'Key name values for @0@'.format(name),
> +      '@INPUT@', name,
> +    ],
> +    capture: true,
> +    build_by_default: true,
> +  )
> +
> +  docs_man_files += {
> +    'name': 'virkeyname-@0@'.format(name), 'section': '7', 'install': true, 'file': rst_file,
> +  }
> +endforeach
> +
> +docs_man_conf = configuration_data()
> +docs_man_conf.set('SYSCONFDIR', sysconfdir)
> +docs_man_conf.set('RUNSTATEDIR', runstatedir)
> +
> +foreach data : docs_man_files
> +  rst_in_file = '@0@.rst.in'.format(data['name'])
> +  html_in_file = '@0@.html.in'.format(data['name'])
> +  html_file = '@0@.html'.format(data['name'])
> +
> +  if data.has_key('file')
> +    rst_file = data['file']
> +  else
> +    rst_file = configure_file(
> +      input: rst_in_file,
> +      output: '@0@.rst'.format(data['name']),
> +      configuration: docs_man_conf,
> +    )
> +  endif

I must say it feels weird process these through configure_file. Also
it's super weird that they've overloaded 3 modes into configure_file.

What's the difference to generator() by the way, since we use it for
rst->html conversion? I'd expect that we could use configure_file there
or generator here then.

Also is there a possibility where the input and output file will have
the same name? I'm not very fond of the .rst.in files.

On Wed, Jul 22, 2020 at 06:51:58PM +0200, Peter Krempa wrote:
> On Thu, Jul 16, 2020 at 11:59:31 +0200, Pavel Hrdina wrote:
> > Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
> > ---
> 
> [...]
> 
> > +foreach name : keyname_list
> > +  rst_file = custom_target(
> > +    'virkeyname-@0@.rst'.format(name),
> > +    input: keymap_src_file,
> > +    output: 'virkeyname-@0@.rst'.format(name),
> > +    command: [
> > +      meson_python_prog, python3_prog, keymap_gen_prog, 'name-docs',
> > +      '--lang', 'rst',
> > +      '--title', 'virkeyname-@0@'.format(name),
> > +      '--subtitle', 'Key name values for @0@'.format(name),
> > +      '@INPUT@', name,
> > +    ],
> > +    capture: true,
> > +    build_by_default: true,
> > +  )
> > +
> > +  docs_man_files += {
> > +    'name': 'virkeyname-@0@'.format(name), 'section': '7', 'install': true, 'file': rst_file,
> > +  }
> > +endforeach
> > +
> > +docs_man_conf = configuration_data()
> > +docs_man_conf.set('SYSCONFDIR', sysconfdir)
> > +docs_man_conf.set('RUNSTATEDIR', runstatedir)
> > +
> > +foreach data : docs_man_files
> > +  rst_in_file = '@0@.rst.in'.format(data['name'])
> > +  html_in_file = '@0@.html.in'.format(data['name'])
> > +  html_file = '@0@.html'.format(data['name'])
> > +
> > +  if data.has_key('file')
> > +    rst_file = data['file']
> > +  else
> > +    rst_file = configure_file(
> > +      input: rst_in_file,
> > +      output: '@0@.rst'.format(data['name']),
> > +      configuration: docs_man_conf,
> > +    )
> > +  endif
> 
> I must say it feels weird process these through configure_file. Also
> it's super weird that they've overloaded 3 modes into configure_file.
> 
> What's the difference to generator() by the way, since we use it for
> rst->html conversion? I'd expect that we could use configure_file there
> or generator here then.

The main difference is that configure_file() is done during meson setup
but generator() is executed while building the project. Another main
difference is that generator() outputs the files into target-private
directory.

There is a note in documentation:

"NOTE: Generators should only be used for outputs that will only be used
as inputs for a build target or a custom target. When you use the
processed output of a generator in multiple targets, the generator will
be run multiple times to create outputs for each target. Each output
will be created in a target-private directory @BUILD_DIR@."

The reason why I went with configure_file is that we create a dictionary
of placeholders that should be replaced in the input file. The other
option would be custom_target() and calling 'sed'.

The reason why we can use generator() for the rst->html.in conversion is
that the output is used in custom_target to create html from html.in
files.

> Also is there a possibility where the input and output file will have
> the same name? I'm not very fond of the .rst.in files.

It should be possible but I prefer using .in suffix to make it clear
that this file needs to be processed.

Pavel

On Wed, Jul 22, 2020 at 19:14:01 +0200, Pavel Hrdina wrote:
> On Wed, Jul 22, 2020 at 06:51:58PM +0200, Peter Krempa wrote:
> > On Thu, Jul 16, 2020 at 11:59:31 +0200, Pavel Hrdina wrote:
> > > Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
> > > ---
> > 
> > [...]
> > 
> > > +foreach name : keyname_list
> > > +  rst_file = custom_target(
> > > +    'virkeyname-@0@.rst'.format(name),
> > > +    input: keymap_src_file,
> > > +    output: 'virkeyname-@0@.rst'.format(name),
> > > +    command: [
> > > +      meson_python_prog, python3_prog, keymap_gen_prog, 'name-docs',
> > > +      '--lang', 'rst',
> > > +      '--title', 'virkeyname-@0@'.format(name),
> > > +      '--subtitle', 'Key name values for @0@'.format(name),
> > > +      '@INPUT@', name,
> > > +    ],
> > > +    capture: true,
> > > +    build_by_default: true,
> > > +  )
> > > +
> > > +  docs_man_files += {
> > > +    'name': 'virkeyname-@0@'.format(name), 'section': '7', 'install': true, 'file': rst_file,
> > > +  }
> > > +endforeach
> > > +
> > > +docs_man_conf = configuration_data()
> > > +docs_man_conf.set('SYSCONFDIR', sysconfdir)
> > > +docs_man_conf.set('RUNSTATEDIR', runstatedir)
> > > +
> > > +foreach data : docs_man_files
> > > +  rst_in_file = '@0@.rst.in'.format(data['name'])
> > > +  html_in_file = '@0@.html.in'.format(data['name'])
> > > +  html_file = '@0@.html'.format(data['name'])
> > > +
> > > +  if data.has_key('file')
> > > +    rst_file = data['file']
> > > +  else
> > > +    rst_file = configure_file(
> > > +      input: rst_in_file,
> > > +      output: '@0@.rst'.format(data['name']),
> > > +      configuration: docs_man_conf,
> > > +    )
> > > +  endif
> > 
> > I must say it feels weird process these through configure_file. Also
> > it's super weird that they've overloaded 3 modes into configure_file.
> > 
> > What's the difference to generator() by the way, since we use it for
> > rst->html conversion? I'd expect that we could use configure_file there
> > or generator here then.
> 
> The main difference is that configure_file() is done during meson setup
> but generator() is executed while building the project. Another main

So how does it then handle if the file is modified prior to another
build? Is 'ninja' re-running the setup phase?

> difference is that generator() outputs the files into target-private
> directory.
> 
> There is a note in documentation:
> 
> "NOTE: Generators should only be used for outputs that will only be used
> as inputs for a build target or a custom target. When you use the
> processed output of a generator in multiple targets, the generator will
> be run multiple times to create outputs for each target. Each output
> will be created in a target-private directory @BUILD_DIR@."
> 
> The reason why I went with configure_file is that we create a dictionary
> of placeholders that should be replaced in the input file. The other
> option would be custom_target() and calling 'sed'.
> 
> The reason why we can use generator() for the rst->html.in conversion is
> that the output is used in custom_target to create html from html.in
> files.
> 
> > Also is there a possibility where the input and output file will have
> > the same name? I'm not very fond of the .rst.in files.
> 
> It should be possible but I prefer using .in suffix to make it clear
> that this file needs to be processed.

I think we should keep the source files named .rst. The .rst format is
good for human consumption even in the pre-processed state.

You can also see different behaviour e.g. when viewing them via gitlab
web interface:

https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/kbase/domainstatecapture.rst

vs

https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/manpages/virt-admin.rst.in

vs current state

https://gitlab.com/libvirt/libvirt/-/blob/master/docs/manpages/virt-admin.rst

On Wed, Jul 22, 2020 at 07:22:34PM +0200, Peter Krempa wrote:
> On Wed, Jul 22, 2020 at 19:14:01 +0200, Pavel Hrdina wrote:
> > On Wed, Jul 22, 2020 at 06:51:58PM +0200, Peter Krempa wrote:
> > > On Thu, Jul 16, 2020 at 11:59:31 +0200, Pavel Hrdina wrote:
> > > > Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
> > > > ---
> > > 
> > > [...]
> > > 
> > > > +foreach name : keyname_list
> > > > +  rst_file = custom_target(
> > > > +    'virkeyname-@0@.rst'.format(name),
> > > > +    input: keymap_src_file,
> > > > +    output: 'virkeyname-@0@.rst'.format(name),
> > > > +    command: [
> > > > +      meson_python_prog, python3_prog, keymap_gen_prog, 'name-docs',
> > > > +      '--lang', 'rst',
> > > > +      '--title', 'virkeyname-@0@'.format(name),
> > > > +      '--subtitle', 'Key name values for @0@'.format(name),
> > > > +      '@INPUT@', name,
> > > > +    ],
> > > > +    capture: true,
> > > > +    build_by_default: true,
> > > > +  )
> > > > +
> > > > +  docs_man_files += {
> > > > +    'name': 'virkeyname-@0@'.format(name), 'section': '7', 'install': true, 'file': rst_file,
> > > > +  }
> > > > +endforeach
> > > > +
> > > > +docs_man_conf = configuration_data()
> > > > +docs_man_conf.set('SYSCONFDIR', sysconfdir)
> > > > +docs_man_conf.set('RUNSTATEDIR', runstatedir)
> > > > +
> > > > +foreach data : docs_man_files
> > > > +  rst_in_file = '@0@.rst.in'.format(data['name'])
> > > > +  html_in_file = '@0@.html.in'.format(data['name'])
> > > > +  html_file = '@0@.html'.format(data['name'])
> > > > +
> > > > +  if data.has_key('file')
> > > > +    rst_file = data['file']
> > > > +  else
> > > > +    rst_file = configure_file(
> > > > +      input: rst_in_file,
> > > > +      output: '@0@.rst'.format(data['name']),
> > > > +      configuration: docs_man_conf,
> > > > +    )
> > > > +  endif
> > > 
> > > I must say it feels weird process these through configure_file. Also
> > > it's super weird that they've overloaded 3 modes into configure_file.
> > > 
> > > What's the difference to generator() by the way, since we use it for
> > > rst->html conversion? I'd expect that we could use configure_file there
> > > or generator here then.
> > 
> > The main difference is that configure_file() is done during meson setup
> > but generator() is executed while building the project. Another main
> 
> So how does it then handle if the file is modified prior to another
> build? Is 'ninja' re-running the setup phase?

Correct, if the source file changes ninja will re-run meson setup phase.

> > difference is that generator() outputs the files into target-private
> > directory.
> > 
> > There is a note in documentation:
> > 
> > "NOTE: Generators should only be used for outputs that will only be used
> > as inputs for a build target or a custom target. When you use the
> > processed output of a generator in multiple targets, the generator will
> > be run multiple times to create outputs for each target. Each output
> > will be created in a target-private directory @BUILD_DIR@."
> > 
> > The reason why I went with configure_file is that we create a dictionary
> > of placeholders that should be replaced in the input file. The other
> > option would be custom_target() and calling 'sed'.
> > 
> > The reason why we can use generator() for the rst->html.in conversion is
> > that the output is used in custom_target to create html from html.in
> > files.
> > 
> > > Also is there a possibility where the input and output file will have
> > > the same name? I'm not very fond of the .rst.in files.
> > 
> > It should be possible but I prefer using .in suffix to make it clear
> > that this file needs to be processed.
> 
> I think we should keep the source files named .rst. The .rst format is
> good for human consumption even in the pre-processed state.
> 
> You can also see different behaviour e.g. when viewing them via gitlab
> web interface:
> 
> https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/kbase/domainstatecapture.rst
> 
> vs
> 
> https://gitlab.com/phrdina/libvirt/-/blob/meson/docs/manpages/virt-admin.rst.in
> 
> vs current state
> 
> https://gitlab.com/libvirt/libvirt/-/blob/master/docs/manpages/virt-admin.rst

OK, this is a solid point which convinced me to remove the .in suffix.

Pavel