From: John Snow <jsnow@redhat.com>
To: Markus Armbruster <armbru@redhat.com>,
Peter Maydell <peter.maydell@linaro.org>
Cc: QEMU Developers <qemu-devel@nongnu.org>
Subject: Re: docs/qemu-qmp-ref.7 markup messed up
Date: Fri, 26 Mar 2021 16:40:31 -0400 [thread overview]
Message-ID: <e8e981b4-871c-23c3-8af1-4411b053e4d9@redhat.com> (raw)
In-Reply-To: <87v99engjp.fsf@dusky.pond.sub.org>
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
next prev parent reply other threads:[~2021-03-26 20:42 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 [this message]
2021-04-06 13:33 ` Markus Armbruster
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=e8e981b4-871c-23c3-8af1-4411b053e4d9@redhat.com \
--to=jsnow@redhat.com \
--cc=armbru@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).