[libvirt PATCH 1/2] docs: kbase: Add a doc on live full disk backup

[Kashyap Chamarthy]

On Fri, May 07, 2021 at 12:29:26PM +0200, Michal Prívozník wrote:
> On 5/4/21 6:16 PM, Kashyap Chamarthy wrote:

[...]

> > Signed-off-by: Kashyap Chamarthy <kchamart at redhat.com>
> > ---
> >  docs/kbase/index.rst                 |   3 +
> >  docs/kbase/live_full_disk_backup.rst | 111 +++++++++++++++++++++++++++
> >  2 files changed, 114 insertions(+)
> >  create mode 100644 docs/kbase/live_full_disk_backup.rst
> 
> Alright, first let me say that's it's difficult to chose which out of
> libxml2 or rst2html gives less useful message on error. More on that below.

:-) I saw the awful error locally after you mentioned "--strict" on IRC.

> You will need to register this file in a list so that meson builds HTML:

Ah, will do.

> diff --git i/docs/kbase/meson.build w/docs/kbase/meson.build
> index 7b4e7abbd3..51d4bc7b90 100644
> --- i/docs/kbase/meson.build
> +++ w/docs/kbase/meson.build
> @@ -6,6 +6,7 @@ docs_kbase_files = [
>    'index',
>    'kvm-realtime',
>    'launch_security_sev',
> +  'live_full_disk_backup',
>    'locking-lockd',
>    'locking',
>    'locking-sanlock',

[...]

> 
> > index 0000000000..f4ef7f2cc7
> > --- /dev/null
> > +++ b/docs/kbase/live_full_disk_backup.rst
> > @@ -0,0 +1,111 @@
> > +Efficient live full disk backup
> > +===============================
> 
> AAand this is the place that rst2html identified as problematic. While
> the true problem is below [1]. Anyway, how about making this h1 type of
> header, and [2].

Ah, strange.  I should've followed existing pattern.  I just wrote the
doc based on the pattern I just go used to:

    h1 content
    ==========
    
    h2 content
    ----------
    
    h3 content
    ~~~~~~~~~~

I'll respin the docs to match the existing convention; it's also
consistent.

> Also, you can generate table of contents here simply by putting:
> 
> .. contents::

Yes; will fix in next iteration.
 
> > +
> > +Overview
> > +--------
> 
> 2: this type h2? I mean putting "==.." at the beginning of the file, and
> s/-/=/

Yeah, it's supposed to be.  Maybe it's only in the Sphinx-based world.
As noted above, I'll re-do it match existing convention.

[...]

> > +Detailed procedure
> > +------------------
> > +
> > +1. Start with a guest with a single disk image, ``base.raw``, which is
> 
> How about replacing "1. 2. 3. ..." with "#."? That way paragraphs will
> get numbered automatically and we won't need to renumber them when
> introducing a new one or shifting them around (unlikely, I know).

I wondered about it too.  I'll change it to the generic "#.".

[...]

> > +   The disk image chain looks as follows::
> > +
> > +    base.raw <-- overlay1.qcow2 (live QEMU)
> > +
> > +.. note::
> 
> 1: this ^^ this is the problem, because it splits this numbered list
> into two. I guess after I found out what the problem was I understand
> the error message a bit:
> 
> ../docs/kbase/live_full_disk_backup.rst:3: (INFO/1) Enumerated list
> start value not ordinal-1: "4" (ordinal 4)

That's an unreadable error from `rst2html5`.  Thanks for digging!  I
didn't hit it as I did not run `rst2html5` with `--strict`. 

> Anyway, putting two spaces at the beginning of the line fixes the
> problem: "   .. note::"

Yep; will fix in next version.  Thanks for the review.

[...]

-- 
/kashyap