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

[Peter Maydell]

On Wed, 26 Feb 2020 at 11:30, Paolo Bonzini <address@hidden> wrote:
>
> This removes the "only" directives, and lets us use the conventional
> "DESCRIPTION" section in the manpage.
>
> Signed-off-by: Paolo Bonzini <address@hidden>
> ---
>  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...)

thanks
-- PMM