ACL documentation fixes

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

Posted by Peter Krempa 2 years, 11 months ago

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@redhat.com>
---
 docs/html/meson.build  | 32 +++++++++++++++++++++++++++++++-
 docs/newapi.xsl        | 12 +++++-------
 src/access/meson.build |  4 ++++
 3 files changed, 40 insertions(+), 8 deletions(-)

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-@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_@0@_xml'.format(name)).full_path(),
       '--stringparam', 'timestamp', docs_timestamp,
       '@INPUT@',
     ],
     install: true,
     install_dir: docs_html_dir / 'html',
+    depends:  get_variable('docs_acl_@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

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

Posted by Daniel P. Berrangé 2 years, 11 months ago

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@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@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-@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_@0@_xml'.format(name)).full_path(),
>        '--stringparam', 'timestamp', docs_timestamp,
>        '@INPUT@',
>      ],
>      install: true,
>      install_dir: docs_html_dir / 'html',
> +    depends:  get_variable('docs_acl_@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 :|

[PATCH 1/6] docs: Fix generated names for ACL objects
[PATCH 2/6] docs: ACL: Mention the ACL object name along with the corresponding libvirt object name
[PATCH 3/6] gendispatch: Add proper XML header to ACL permissions XML file
[PATCH 4/6] docs/html: Properly generate ACL permissions into API reference
[PATCH 5/6] docs: Distribute the XMLs with ACL permission flags for APIs
[PATCH 6/6] examples: polkit: Grant 'domain.read-secure' for the example cases