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@xxxxxxxxxx>
> > ---
> > 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
