Re: [PATCH 13/18] docs/system: put qemu-block-drivers body in an included file

From: "Daniel P. Berrangé" <berrange@redhat.com>
To: Peter Maydell <peter.maydell@linaro.org>
Cc: Paolo Bonzini <pbonzini@redhat.com>,
	QEMU Developers <qemu-devel@nongnu.org>
Subject: Re: [PATCH 13/18] docs/system: put qemu-block-drivers body in an included file
Date: Thu, 27 Feb 2020 13:28:08 +0000	[thread overview]
Message-ID: <20200227132808.GJ1645630@redhat.com> (raw)
In-Reply-To: <CAFEAcA_qWUY19ubmSaNoqbwjf8N8d1Dw=vMMD7j5yH8TSwK35A@mail.gmail.com>

On Thu, Feb 27, 2020 at 11:58:27AM +0000, Peter Maydell wrote:
> On Wed, 26 Feb 2020 at 11:30, Paolo Bonzini <pbonzini@redhat.com> wrote:
> >
> > This removes the "only" directives, and lets us use the conventional
> > "DESCRIPTION" section in the manpage.
> >
> > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> > ---
> >  docs/system/index.rst                  |   2 -
> >  docs/system/qemu-block-drivers.rst     | 987 +------------------------
> >  docs/system/qemu-block-drivers.rst.inc | 954 ++++++++++++++++++++++++
> >  3 files changed, 966 insertions(+), 977 deletions(-)
> >  create mode 100644 docs/system/qemu-block-drivers.rst.inc
> >
> > diff --git a/docs/system/index.rst b/docs/system/index.rst
> > index f66e6ea585..21b5a18b67 100644
> > --- a/docs/system/index.rst
> > +++ b/docs/system/index.rst
> > @@ -13,5 +13,3 @@ Contents:
> >
> >  .. toctree::
> >     :maxdepth: 2
> > -
> > -   qemu-block-drivers
> 
> Why do you drop the documentation from the HTML manual ?
> 
> Is the changing in the underline styles for section
> headings necessary? It's non-obvious in the diff format
> the patch in the email has, but with my local git diff
> settings (algorithm=histogram) it shows up better:
> 
> > Secure Shell (ssh) disk images
> >-------------------------------
> >+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> Given that rST figures out subsection depth automatically
> rather than based on which particular character is used
> maybe we could avoid the noise in the diff?
> 
> (OTOH, we should probably pick a rST style guide for which
> characters to use for which section headings and follow
> it here to avoid unnecessarily confusing ourselves...)

Yes, I'd encourage explicitly documenting the required section
heading chars in particular, as otherwise we get a free for all
which becomes confusing, especially if we need to move
text from one doc into another doc.

For libvirt we chose:

  =========
  Heading 1
  =========

  Heading 2
  =========

  Heading 3
  ---------

  Heading 4
  ~~~~~~~~~

  Heading 5
  .........

  Heading 6
  ^^^^^^^^^

Heading 6 looks a bit odd, but on the flipside it should almost never
need to be used.  https://libvirt.org/styleguide.html

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|