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