Re: [Qemu-devel] [PATCH v3 01/12] docs/cpu-hotplug.rst: Fix rST markup issues

[Cleber Rosa <crosa@redhat.com>]

On Tue, Mar 05, 2019 at 05:21:28PM +0000, Peter Maydell wrote:
> sphinx-build complains:
> 
> docs/cpu-hotplug.rst:67: ERROR: Unexpected indentation.
> docs/cpu-hotplug.rst:69: ERROR: Unexpected indentation.
> docs/cpu-hotplug.rst:74: WARNING: Block quote ends without a blank line; unexpected unindent.
> docs/cpu-hotplug.rst:75: WARNING: Block quote ends without a blank line; unexpected unindent.
> docs/cpu-hotplug.rst:76: SEVERE: Unexpected section title.
> 
> }
> {
> docs/cpu-hotplug.rst:78: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> These are the result of not indicating one of the literal
> blocks by finishing the preceding paragraph with the "::" marker.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-2-peter.maydell@linaro.org
> ---
>  docs/cpu-hotplug.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/docs/cpu-hotplug.rst b/docs/cpu-hotplug.rst
> index 1c268e00b41..e2d4e893b01 100644
> --- a/docs/cpu-hotplug.rst
> +++ b/docs/cpu-hotplug.rst
> @@ -60,7 +60,7 @@ vCPU hotplug
>      hot-plugged (no "qom-path" member).  From its output in step (3), we
>      can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0,
>      while hot-plugging a CPU into socket 1 requires passing the listed
> -    properties to QMP ``device_add``:
> +    properties to QMP ``device_add``::
>  
>        (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0
>        {
> -- 
> 2.20.1
> 
> 

This is an actual reStructuredText syntax violation (at a layer lower
than sphinx) and thus can also be seen by simpler tools such as
rst2{man,html,...}:

   $ rst2html docs/cpu-hotplug.rst 1>/dev/null 
   docs/cpu-hotplug.rst:67: (ERROR/3) Unexpected indentation.
   docs/cpu-hotplug.rst:69: (ERROR/3) Unexpected indentation.
   docs/cpu-hotplug.rst:74: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
   docs/cpu-hotplug.rst:75: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
   docs/cpu-hotplug.rst:76: (SEVERE/4) Unexpected section title.

   }
   {
   Exiting due to level-4 (SEVERE) system message.

But I'm assuming the extended sphinx roles/directives will be used, so
the only way to check against future breakage would be to build the
docs.

Do we have strong position in favor or against putting that into the
"common" `make check` flow?  Anyway, these are all possibilities for
future enhancements, so:

Reviewed-by: Cleber Rosa <crosa@redhat.com>