[libvirt PATCH 7/9] docs: html.in: Convert auth to rst

Fri Mar 12 12:54:05 UTC 2021

On Fri, Mar 12, 2021 at 12:43:10 +0100, Erik Skultety wrote:
> Signed-off-by: Erik Skultety <eskultet at redhat.com>
> ---
>  docs/auth.html.in | 368 ----------------------------------------------
>  docs/auth.rst     | 343 ++++++++++++++++++++++++++++++++++++++++++
>  docs/meson.build  |   2 +-
>  3 files changed, 344 insertions(+), 369 deletions(-)
>  delete mode 100644 docs/auth.html.in
>  create mode 100644 docs/auth.rst
> 
> diff --git a/docs/auth.html.in b/docs/auth.html.in
> deleted file mode 100644
> index 9b940a8598..0000000000
> --- a/docs/auth.html.in
> +++ /dev/null
> @@ -1,368 +0,0 @@
> -<?xml version="1.0" encoding="UTF-8"?>
> -<!DOCTYPE html>
> -<html xmlns="http://www.w3.org/1999/xhtml">
> -  <body>
> -    <h1>Connection authentication</h1>
> -    <p>
> -      When connecting to libvirt, some connections may require client
> -      authentication before allowing use of the APIs. The set of possible
> -      authentication mechanisms is administrator controlled, independent
> -      of applications using libvirt. Once authenticated, libvirt can apply
> -      fine grained <a href="acl.html">access control</a> to the operations
> -      performed by a client.
> -    </p>
> -
> -    <ul id="toc"></ul>
> -
> -    <h2><a id="Auth_client_config">Client configuration</a></h2>

docs/kbase/locking-sanlock.rst links to this anchor:

file <auth.html#Auth_client_config>`__ needs to contain something like

[...]

> diff --git a/docs/auth.rst b/docs/auth.rst
> new file mode 100644
> index 0000000000..26fa6c950c
> --- /dev/null
> +++ b/docs/auth.rst
> @@ -0,0 +1,343 @@
> +=========================
> +Connection authentication
> +=========================
> +
> +When connecting to libvirt, some connections may require client
> +authentication before allowing use of the APIs. The set of possible
> +authentication mechanisms is administrator controlled, independent of
> +applications using libvirt. Once authenticated, libvirt can apply fine
> +grained `access control <acl.html>`__ to the operations performed by a
> +client.
> +
> +.. contents::
> +
> +Client configuration
> +--------------------

But docutils will generate an anchor with a different name here, since
the name is based on the heading.

You'll need to tweak the other file too in this case. I think that
breaking the anchor is okay though in this instance and ugly hacks to
preserve anchor names as done in formatdomain.rst are not needed.