On Sun, 5 Jun 2022 at 01:16, <oxr...@gmx.us> wrote: > > From: Lucas Ramage <lucas.ram...@infinite-omicron.com> > > Buglink: https://gitlab.com/qemu-project/qemu/-/issues/527 > Signed-off-by: Lucas Ramage <lucas.ram...@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
