[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Peter Maydell
Subject: Re: [PATCH] docs/devel/*.txt: convert remaining files to restructuredText
Date: Thu, 9 Jun 2022 14:39:45 +0100

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):


quote ends without a blank line; unexpected unindent.

emphasis start-string without end-string.

list ends without a blank line; unexpected unindent.


emphasis start-string without end-string.

emphasis start-string without end-string.

emphasis start-string without end-string.


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.

-- PMM

reply via email to

[Prev in Thread] Current Thread [Next in Thread]