From: Markus Armbruster <armbru@redhat.com>
To: John Snow <jsnow@redhat.com>
Cc: Peter Maydell <peter.maydell@linaro.org>,
Markus Armbruster <armbru@redhat.com>,
QEMU Developers <qemu-devel@nongnu.org>
Subject: Re: docs/qemu-qmp-ref.7 markup messed up
Date: Tue, 06 Apr 2021 15:33:39 +0200 [thread overview]
Message-ID: <87blar7d1o.fsf@dusky.pond.sub.org> (raw)
In-Reply-To: <e8e981b4-871c-23c3-8af1-4411b053e4d9@redhat.com> (John Snow's message of "Fri, 26 Mar 2021 16:40:31 -0400")
John Snow <jsnow@redhat.com> writes:
> On 3/26/21 10:19 AM, Markus Armbruster wrote:
>> When I look at docs/qemu-qmp-ref.7 with less -R, I see
>> ReplicationMode (Enum)
>> An enumeration of replication modes.
>> Values
>> primary
>> Primary mode, the vm's state will be sent to secondary QEMU.
>> secondary
>> Secondary mode, receive the vm's state from primary QEMU.
>> Since
>> 2.9
>> If
>> --> defined(CONFIG_REPLICATION).SS BlockdevOptionsReplication (Object)
>> Driver specific block device options for replication
>> Members
>> mode: ReplicationMode
>> the replication mode
>> The line I marked with --> is bad. It should instead look like
>> If
>> defined(CONFIG_REPLICATION)
>> BlockdevOptionsReplication (Object)
>> Driver specific block device options for replication
>> Unformatted code:
>> .SS \fBReplicationMode\fP (Enum)
>> .sp
>> An enumeration of replication modes.
>> .SS Values
>> .INDENT 0.0
>> .TP
>> .B \fBprimary\fP
>> Primary mode, the vm\(aqs state will be sent to secondary QEMU.
>> .TP
>> .B \fBsecondary\fP
>> Secondary mode, receive the vm\(aqs state from primary QEMU.
>> .UNINDENT
>> .SS Since
>> .sp
>> 2.9
>> .SS If
>> --> \fBdefined(CONFIG_REPLICATION)\fP.SS \fBBlockdevOptionsReplication\fP (Object)
>> .sp
>> Driver specific block device options for replication
>> .SS Members
>> .INDENT 0.0
>> .TP
>> .B \fBmode\fP: \fBReplicationMode\fP
>> the replication mode
>> .TP
>> I believe line I marked with --> should be broken before .SS.
>> I'm using sphinx-build-3 2.2.2.
>> I checked with the merge commit that switched QAPI doc generation to
>> Sphinx (commit e344ffe73b), same result.
>>
>
> It looks like that's consistent for every case I can see for
> "defined(...)", where the .SS bit comes immediately on the same line.
>
> _nodes_for_if_section seems to handle the docutil tree creation for
> the stuff in question, here, I think?
>
> I changed the heading to "IfZ" to make it nicer to grep, and then If I
> pepper in some prints (mercifully docutils has very nice __str__
> methods!) I can see this type of stuff:
>
> <section
> ids="qapidoc-713"><title>IfZ</title><literal>defined(CONFIG_REPLICATION)</literal></section>
> <section
> ids="qapidoc-717"><title>IfZ</title><literal>defined(CONFIG_REPLICATION)</literal></section>
>
> Hm, I think <literal> is not a block-level element, and maybe there's
> a bug/intentional-design-choice/bug where it can't handle a non-block
> child of a section correctly?
>
> Let me try wrapping it in a PARAGRAPH node...
>
> .SS IfZ
> .sp
> \fBdefined(CONFIG_REPLICATION)\fP
> .SS \fBBlockdevOptionsReplication\fP (Object)
> .sp
>
>
> That looks better, I think.
>
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index b7b86b5dff..b7a2d39c10 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -278,7 +278,9 @@ def _nodes_for_if_section(self, ifcond):
> nodelist = []
> if ifcond:
> snode = self._make_section('If')
> - snode += self._nodes_for_ifcond(ifcond, with_if=False)
> + snode += nodes.paragraph(
> + '', '', *self._nodes_for_ifcond(ifcond, with_if=False)
> + )
> nodelist.append(snode)
> return nodelist
>
>
> Signed-off-by: John Snow <jsnow@redhat.com>
>
> --js
Fixes the issue for me, thanks!
Tested-by: Markus Armbruster <armbru@redhat.com>
Please post as a proper patch.
prev parent reply other threads:[~2021-04-06 13:34 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-03-26 14:19 docs/qemu-qmp-ref.7 markup messed up Markus Armbruster
2021-03-26 20:40 ` John Snow
2021-04-06 13:33 ` Markus Armbruster [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87blar7d1o.fsf@dusky.pond.sub.org \
--to=armbru@redhat.com \
--cc=jsnow@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).