Re: [PATCH] docs/devel/*.txt: convert remaining files to restructuredText

[Peter Maydell]

On Sun, 5 Jun 2022 at 01:16, <oxr463@gmx.us> wrote:
>
> From: Lucas Ramage <lucas.ramage@infinite-omicron.com>
>
> Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527
> Signed-off-by: Lucas Ramage <lucas.ramage@infinite-omicron.com>
> ---
>  docs/devel/{blkdebug.txt => blkdebug.rst}     |  8 +++++-
>  docs/devel/{blkverify.txt => blkverify.rst}   | 12 ++++++---
>  docs/devel/index-build.rst                    |  2 ++
>  docs/devel/index-internals.rst                |  5 ++++
>  docs/devel/{lockcnt.txt => lockcnt.rst}       | 25 ++++++++++---------
>  ...e-iothreads.txt => multiple-iothreads.rst} |  3 +++
>  docs/devel/{rcu.txt => rcu.rst}               |  0
>  docs/devel/{replay.txt => replay.rst}         | 11 +++++---
>  ...tio-migration.txt => virtio-migration.rst} |  6 ++---
>  9 files changed, 48 insertions(+), 24 deletions(-)
>  rename docs/devel/{blkdebug.txt => blkdebug.rst} (99%)
>  rename docs/devel/{blkverify.txt => blkverify.rst} (94%)
>  rename docs/devel/{lockcnt.txt => lockcnt.rst} (95%)
>  rename docs/devel/{multiple-iothreads.txt => multiple-iothreads.rst} (99%)
>  rename docs/devel/{rcu.txt => rcu.rst} (100%)
>  rename docs/devel/{replay.txt => replay.rst} (96%)
>  rename docs/devel/{virtio-migration.txt => virtio-migration.rst} (98%)

Thanks for these conversions. Unfortunately at least the version
of Sphinx I have doesn't seem to be happy with them :-(

replay.txt was converted in commit 04d0583a4f5d000 already.

On my version of Sphinx there are a number of errors reported
(since Sphinx bails out on first error you need to fix up each
one to see the next):

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/blkverify.rst:70:Unexpected
indentation.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:43:Block
quote ends without a blank line; unexpected unindent.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:89:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:103:Definition
list ends without a blank line; unexpected unindent.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:112:Unexpected
indentation.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:120:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:129:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/rcu.rst:151:Inline
emphasis start-string without end-string.

/mnt/nvmedisk/linaro/qemu-from-laptop/qemu/docs/devel/virtio-migration.rst:12:Unexpected
indentation.


These are caused largely by two things:

(1) An indented section in the documentation that's intended to be
an ASCII-art diagram or command line example and should be rendered
in fixed-width text needs to be preceded by a double-colon. Otherwise
it's just a normal indented paragraph (and if it has things like
multiple lines with indentation of their own then Sphinx will complain
about incorrect intendation).

(2) Text like
 typeof(*p) qatomic_rcu_read(p);
needs to be surrounded by ``...`` so that the '*' isn't interpreted as
the *emphasis* markup (and also so it ends up as fixed-width font).
That in turn means that we should mark up the other cases in rcu.rst
similarly even if they happen not to have '*' characters, for consistency.

Also, if you look at the rendered HTML for these files you'll
see it looks a bit odd where Sphinx's formatting rules don't find
the input text to be a syntax error but still aren't interpreting
it the way the original text documentation was written, as for
instance in the list of rule attributes in blkdebug.rst.

Finally, when a .txt file has a copyright/license statement in it,
we don't want that to appear in the rendered HTML documentation.
We handle this by putting it in a Sphinx comment. There's an
example of this in docs/system/replay.rst.

Since all that implies that each of these files is going to need a bit
more changes than just fixing up the section titles, I think it
would probably be preferable to split this into more than one commit.

thanks
-- PMM