[ovs-dev] [RFC 2/2] doc: Convert ovs-vswitchd to rST

Ben Pfaff blp at ovn.org
Thu May 25 17:25:16 UTC 2017


On Fri, May 19, 2017 at 10:48:06AM +0100, Stephen Finucane wrote:
> On Thu, 2017-05-18 at 16:02 -0700, Ben Pfaff wrote:
> > Bravo.  This must have been a lot of work.
> > 
> > More comments follow...
> > 
> > On Wed, May 10, 2017 at 09:32:19PM -0400, Stephen Finucane wrote:
> > > This is the largest man page by some distance. There are a couple
> > > of changes needed to make this work:
> > > 
> > > - Combining italics and bold without spaces (i.e. <b>hello</b>-
> > > <i>world</i>) and nesting italics and bold (i.e. <b><i>hello-
> > > world</i></b>) is not supported by rST. Where present, this has
> > > been removed.
> > > 
> > > - Duplicated opts are not possible. Where before we would have had
> > > a list like so:
> > > 
> > >     -vPATTERN:destination:pattern
> > >       Description
> > > 
> > >     -vFACILITY:facility
> > >       Description
> > > 
> > >    We now have:
> > > 
> > >      -v <verbosity>
> > > 
> > >        PATTERN:<destination>:<pattern>
> > >          Description
> > > 
> > >        FACILITY:<facility>
> > >          Description
> > > 
> > >   This is necessary if we want to make best use of the Sphinx
> > > indexing.
> > 
> > I'm not too aware of Sphinx indexing.  When I type "Sphinx indexing"
> > into Google, it tells me about a search engine named Sphinx, which I
> > don't think is what you mean.  Can you point to something about it?
> 
> Sure - here's the example from our own docs:
> 
> http://docs.openvswitch.org/en/latest/genindex/

Hmm, that seems nice, but I wonder to what extent users use it versus
full-text search.

It also seems possible to manually add index entries via .. index:: and
:index: (see www.sphinx-doc.org/en/stable/markup/misc.html).  If we are
concerned that the index should be complete (which is a fair concern),
but there are entries that do not fit the form that generates an index
entry automatically, then we could manually index those forms.

> > If the indexing is just a matter of being able to jump to the
> > definition of -v from somewhere else, I wonder whether it matters
> > whether both definitions are indexed?  I think that both definitions
> > would be right next to each other in this case.
> 
> In fairness, it probably doesn't. I'll change this to use 'object' for
> all except the most basic, no-arg one. 'object' produces the same
> formatting as 'option' but doesn't generate a reference/add things to
> the index.
> 
> > There's a bigger problem with the above transformation, though: -v
> > takes an optional argument, which means that only accepts an argument
> > if the argument is mashed up against it.  If you write "-v ..." with
> > a space, it's not an argument, it's "-v" followed by a non-option
> > argument.
> 
> They didn't account for this when writing the Sphinx directive, clearly
> :) We should resolve this particular case with the above change, but
> I'll have to rely on you to look for any other cases I've missed.

At least some of the Python option parsers do not support optional
arguments (which are kind of ugly in any case, but...), so it is a
natural assumption for Python-focused programmers to make.

> > > - TODO
> > > 
> > > Signed-off-by: Stephen Finucane <stephen at that.guru>
> > >
> > > - There's a big loss of formatting for subcommands. While I don't
> > > think the bit of loss in the option descriptions is _that_ big a
> > > deal, the subcommands are longer and could benefit from the
> > > formatting more. I could probably fix it in Sphinx internally for
> > > Sphinx 1.6, but that'd take a year or two to propagate to distros.
> > 
> > I don't understand the issue yet.  What happens if we just use RST
> > that produces the desired formatting?  (Is this about indexing
> > again?)
> 
> Two issues. First, take a look at the current ovs-vswitchd doc:
> 
>   http://openvswitch.org/support/dist-docs/ovs-vswitchd.8.html
> 
> If you look at the 'ssl:ip:port' description, you'll note that 'ssl' is
>  in bold, 'ip' and 'port' are underlined, and the colons in between
> have no formatting. We can't do this in Sphinx as you need spaces
> between inline formatting markers.

Ouch.  That prevents formatting so many things!  It seems like a
significant limitation in RST.  In RST, how do authors distinguish
between literal characters (bold, in manpages), variables (italic, in
manpages), and metacharacters like []|{} (roman, in manpages)?  It seems
to be a common convention to use <> to surround variables, which is fine
with me, but what about literal versus meta?

> Secondly, look at an example of the 'option' directive, e.g.:
> 
>    .. option:: -V, --version
> 
>        Prints version information to the console.
> 
> This can be viewed like so:
> 
>    .. <directive_name>:: <directive arguments>
> 
>       <directive contents>
> 
> While '<directive contents>' is parsed as reStructuredText, '<directive
> arguments>' is not. This means if we include things like '*' (italics),
> '**' (bold), or '``' (code/literal), they'll be rendered as they are.

OK.  I guess that in practice limits us to one font, so we need to use
<> for variables, [] for optional, etc., and hope that there are few
ambiguities or that we can resolve the ones that arise with text and
examples.

> IMO, the option directive provides enough usefulness to make this
> worthwhile, but I called it out just in case.

OK.

> > > - I'm not sure if there's a way to use this kind of macro:
> > > 
> > >     \*(DX\fBadd\-dp \fIdp\fR [\fInetdev\fR[\fB,\fIoption\fR]...]
> > > 
> > >   which is called like so:
> > > 
> > >     .ds DX \fBdpctl/\fR
> > >     .de DO
> > >     \\$2 \\$1 \\$3
> > > 
> > >   and yields:
> > > 
> > >     dpctl/add-dp dp [netdev[,option]...]
> > > 
> > >   This will probably result in some duplication, else a _lot_ of
> > > 'inc'
> > >   files
> > 
> > We could always just document these commands in only one place, e.g.
> > the ovs-dpctl manpage, and then refer to that manpage from ovs-
> > vswitchd manpage with a little extra explanation, e.g. "You can use
> > ovs-dpctl commands via ovs-appctl: instead of 'ovs-dpctl show', type
> > 'ovs-appctl dpctl/show'."
> 
> I'd thought about duplicating the info instead. However, if you're
> happy to simply reference things, then this is good by me.

References are OK, I think.

> > > - I'm not sure how we should pass in autoconf (?) variables like
> > >   @RUNDIR at . Could we do this in Python or something?
> > 
> > I haven't done the right research on this yet.
> 
> I guess we could just start statically defining these, with a statement
> that things may change depending on your installation. If not, I'll
> think of something :)

Let's try statically defining them.

I am not sure what the defaults should be.  There is some tension
between the Autoconf defaults, based on /usr/local, and the most common
installation directories on the packaging for GNU/Linux systems, based
on /usr.  Either one that we choose will confuse or surprise some users:
anyone installing from packaging will have files in /usr, but anyone who
just types "./configure" without adding directory options will have
files in /usr/local.

> > > - Some other stuff that I've forgotten
> > > 
> > > In any case though, it should go folks a rough idea of what a
> > > larger man page in rST/Sphinx will actually look like.
> > 
> > I notice that in PDF builds, long lines in examples get cut off at
> > the right margin instead of line-wrapping, which is unfortunate.
> 
> Do we care about the PDF builds? I'd considered disabling those,
> personally. If we do, then I'm sure there'll be something on
> StackOverflow about that exact problem, heh.

Hmm.

I don't care much about PDF builds of the documentation in general, but
for manpages, my habit is to view a nicely rendered version by typing,
e.g.  "groffer vswitchd/ovs-vswitchd.conf.db.5", which by default
converts to PDF and then launches a PDF viewer.  That's not really a
"PDF build", since it's generated by groff, not Sphinx.  So I tend to
notice stuff that renders badly in PDF as manpages.  What's your usual
workflow for viewing a rendered RST file?


More information about the dev mailing list