[PATCH 4/6] docs/html: Properly generate ACL permissions into API reference

[Daniel P. Berrangé]

On Mon, Feb 20, 2023 at 11:47:07AM +0100, Peter Krempa wrote:
> The 'newapi.xsl' stylesheet was referencing non-existing paths to the
> XML files holding ACL permission flags for individual APIs. Additionally
> the 'document()' XSL function doesn't even allow concatenation of the
> path as it was done via '{$builddir}/src..', but requires either direct
> argument or use of the 'concat()' function.
> 
> This meant that the 'acls' variable was always empty and thus none of
> our API documentation was actually generated with the 'acl' section.
> 
> Fix it by passing the path to the XML via an argument to the stylesheet
> as the files differ based on which document is being generated.
> 
> Since the 'admin' API does not have ACL we need to handle it separately
> now in the build system.
> 
> Signed-off-by: Peter Krempa <pkrempa at redhat.com>
> ---
>  docs/html/meson.build  | 32 +++++++++++++++++++++++++++++++-
>  docs/newapi.xsl        | 12 +++++-------
>  src/access/meson.build |  4 ++++
>  3 files changed, 40 insertions(+), 8 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange at redhat.com>


> 
> diff --git a/docs/html/meson.build b/docs/html/meson.build
> index b18a8ccb5f..4e818f9142 100644
> --- a/docs/html/meson.build
> +++ b/docs/html/meson.build
> @@ -27,12 +27,14 @@ index_api_gen = custom_target(
>    command: [
>      xsltproc_prog, '--nonet', '-o', docs_builddir,
>      '--stringparam', 'builddir', meson.project_build_root(),
> +    '--stringparam', 'aclxmlpath', docs_acl_xml.full_path(),
>      '--stringparam', 'timestamp', docs_timestamp,
>      '--stringparam', 'indexfile', 'index.html',
>      '@INPUT@',
>    ],
>    install: true,
>    install_dir: docs_html_dir / 'html',
> +  depends: docs_acl_xml,
>    depend_files: [
>      page_xsl,
>    ],
> @@ -41,7 +43,7 @@ index_api_gen = custom_target(
>  docs_html_gen += index_api_gen.to_list()
>  docs_html_dep += index_api_gen
> 
> -foreach name : [ 'admin', 'lxc', 'qemu' ]
> +foreach name : [ 'lxc', 'qemu' ]
>    index_api_gen = custom_target(
>      'index- at 0@-api'.format(name),
>      input: [
> @@ -54,11 +56,13 @@ foreach name : [ 'admin', 'lxc', 'qemu' ]
>      command: [
>        xsltproc_prog, '--nonet', '-o', docs_builddir,
>        '--stringparam', 'builddir', meson.project_build_root(),
> +      '--stringparam', 'aclxmlpath', get_variable('docs_acl_ at 0@_xml'.format(name)).full_path(),
>        '--stringparam', 'timestamp', docs_timestamp,
>        '@INPUT@',
>      ],
>      install: true,
>      install_dir: docs_html_dir / 'html',
> +    depends:  get_variable('docs_acl_ at 0@_xml'.format(name)),
>      depend_files: [
>        page_xsl,
>      ],
> @@ -68,6 +72,32 @@ foreach name : [ 'admin', 'lxc', 'qemu' ]
>    docs_html_dep += index_api_gen
>  endforeach
> 
> +index_api_gen = custom_target(
> +  'index-admin-api'.format(name),
> +  input: [
> +    newapi_xsl,
> +    docs_admin_api_xml,
> +    ],
> +  output: [
> +    'libvirt-libvirt-admin.html'
> +    ],
> +  command: [
> +    xsltproc_prog, '--nonet', '-o', docs_builddir,
> +    '--stringparam', 'builddir', meson.project_build_root(),
> +    '--stringparam', 'aclxmlpath', '',
> +    '--stringparam', 'timestamp', docs_timestamp,
> +    '@INPUT@',
> +    ],
> +  install: true,
> +  install_dir: docs_html_dir / 'html',
> +  depend_files: [
> +    page_xsl,
> +    ],
> +  )
> +
> +docs_html_gen += index_api_gen.to_list()
> +docs_html_dep += index_api_gen
> +
>  docs_html_paths = []
> 
>  install_web_deps += docs_html_dep
> diff --git a/docs/newapi.xsl b/docs/newapi.xsl
> index 3de603bb00..cc3ec681b7 100644
> --- a/docs/newapi.xsl
> +++ b/docs/newapi.xsl
> @@ -24,18 +24,16 @@
> 
>    <xsl:param name="indexfile" select="''"/>
> 
> +  <xsl:param name="aclxmlpath" select="''"/>
> +
>    <!-- the target directory for the HTML output -->
>    <xsl:variable name="htmldir">html</xsl:variable>
>    <xsl:variable name="href_base">../</xsl:variable>
> 
>    <xsl:variable name="acls">
> -    <xsl:copy-of select="document('{$builddir}/src/libvirt_access.xml')/aclinfo/api"/>
> -  </xsl:variable>
> -  <xsl:variable name="qemuacls">
> -    <xsl:copy-of select="document('{$builddir}/src/libvirt_access_qemu.xml')/aclinfo/api"/>
> -  </xsl:variable>
> -  <xsl:variable name="lxcacls">
> -    <xsl:copy-of select="document('{$builddir}/src/libvirt_access_lxc.xml')/aclinfo/api"/>
> +    <xsl:if test="$aclxmlpath != ''">
> +      <xsl:copy-of select="document($aclxmlpath)/aclinfo/api"/>
> +    </xsl:if>
>    </xsl:variable>
> 
>    <xsl:template name="aclinfo">
> diff --git a/src/access/meson.build b/src/access/meson.build
> index 07fd7d372e..0b12581dc1 100644
> --- a/src/access/meson.build
> +++ b/src/access/meson.build
> @@ -74,6 +74,10 @@ foreach name : [ 'remote', 'qemu', 'lxc' ]
>    )
>  endforeach
> 
> +docs_acl_xml = access_gen_xml[0]
> +docs_acl_qemu_xml = access_gen_xml[1]
> +docs_acl_lxc_xml = access_gen_xml[2]
> +
>  if conf.has('WITH_POLKIT')
>    access_sources += access_polkit_sources
> 
> -- 
> 2.39.2
> 

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|