[Qemu-commits] [qemu/qemu] 0defa8: docs/cpu-hotplug.rst: Fix rST markup issues

[Peter Maydell]

  Branch: refs/heads/master
  Home:   https://github.com/qemu/qemu
  Commit: 0defa86ca372efd4a60259c970181a66d3b24304
      
https://github.com/qemu/qemu/commit/0defa86ca372efd4a60259c970181a66d3b24304
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M docs/cpu-hotplug.rst

  Log Message:
  -----------
  docs/cpu-hotplug.rst: Fix rST markup issues

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 <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Tested-by: Philippe Mathieu-Daudé <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Reviewed-by: Cleber Rosa <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 859cdc01a0f9d914fa74892270d40516398d089a
      
https://github.com/qemu/qemu/commit/859cdc01a0f9d914fa74892270d40516398d089a
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    A docs/devel/memory.rst
    R docs/devel/memory.txt

  Log Message:
  -----------
  docs: Convert memory.txt to rst format

Convert the memory API documentation from plain text
to restructured text format.

This is a very minimal conversion: all I had to change
was to mark up the ASCII art parts as Sphinx expects
for 'literal blocks', and fix up the bulleted lists
(Sphinx expects no leading space before the bullet, and
wants a blank line before after any list).

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Reviewed-by: Cleber Rosa <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 5329da6a4f65b394a3131e00af142ad5294345c1
      
https://github.com/qemu/qemu/commit/5329da6a4f65b394a3131e00af142ad5294345c1
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    A docs/conf.py
    A docs/index.rst

  Log Message:
  -----------
  docs: Commit initial files from sphinx-quickstart

Commit the initial Sphinx conf.py and skeleton index.rst as
generated with sphinx-quickstart. We'll update these to
add QEMU-specific tweaks in subsequent commits.

Signed-off-by: Peter Maydell <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Acked-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 07fd6563ae435cc78ec64d245a59d13373c2c686
      
https://github.com/qemu/qemu/commit/07fd6563ae435cc78ec64d245a59d13373c2c686
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M docs/conf.py

  Log Message:
  -----------
  docs/conf.py: Disable unused _static directory

We don't yet have any custom static files, so disable this
config file setting to avoid a warning from sphinx about
not being able to find the directory.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 4fad3864a88170fd16f59b73b0d6a3b3c29692dc
      
https://github.com/qemu/qemu/commit/4fad3864a88170fd16f59b73b0d6a3b3c29692dc
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M docs/conf.py

  Log Message:
  -----------
  docs/conf.py: Configure the 'alabaster' theme

Add the 'navigation' bar to the sidebar, which for some
reason is not enabled by default. Remove 'relations', which
is effectively disabled anyway and isn't useful for us.

This requires that we mandate having at least Sphinx 1.3,
where the theme was added.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 479fb8a5114cc87fdf96bb21e4cf0b5798286444
      
https://github.com/qemu/qemu/commit/479fb8a5114cc87fdf96bb21e4cf0b5798286444
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M docs/conf.py

  Log Message:
  -----------
  docs/conf.py: Don't include rST sources in HTML build

Sphinx defaults to including all the rST source files
in the HTML build and making each HTML page link to the
source file. Disable that.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: e250e867dc0172203b30aa25032efe29f1102b21
      
https://github.com/qemu/qemu/commit/e250e867dc0172203b30aa25032efe29f1102b21
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M docs/conf.py

  Log Message:
  -----------
  docs/conf.py: Disable option warnings

sphinx-build complains about using :option: to mark up option
flags that it doesn't know about (because they were not defined
using the "option::" directive):
docs/pr-manager.rst:68: WARNING: unknown option: -d

Suppress these warnings. This way we get the semantic markup
of the option flag but no cross-referencing hyperlink.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: f8cf7147f10a3cee64396614218b08e3c9161d4a
      
https://github.com/qemu/qemu/commit/f8cf7147f10a3cee64396614218b08e3c9161d4a
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M docs/conf.py
    A docs/devel/conf.py
    A docs/devel/index.rst
    M docs/index.rst
    A docs/interop/conf.py
    A docs/interop/index.rst

  Log Message:
  -----------
  docs: Provide separate conf.py for each manual we want

By default Sphinx wants to build a single manual at once.
For QEMU, this doesn't suit us, because we want to have
separate manuals for "Developer's Guide", "User Manual",
and so on, and we don't want to ship the Developer's Guide
to end-users. However, we don't want to completely duplicate
conf.py for each manual, and we'd like to continue to
support "build all docs in one run" for third-party sites
like readthedocs.org.

Make the top-level conf.py support two usage forms:
 (1) as a common config file which is included by the conf.py
 for each of QEMU's manuals: in this case sphinx-build is run
 multiple times, once per subdirectory.
 (2) as a top level conf file which will result in building all
 the manuals into a single document: in this case sphinx-build is
 run once, on the top-level docs directory.

Provide per-manual conf.py files and top level pages for
our first two manuals:
 * QEMU Developer's Guide (docs/devel)
 * QEMU System Emulation Management and Interoperability Guide
   (docs/interop)

Reviewed-by: Alex Bennée <address@hidden>
Signed-off-by: Peter Maydell <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 5f71eac06e15b9a3fa1134d446f0ca2d52e45f0a
      
https://github.com/qemu/qemu/commit/5f71eac06e15b9a3fa1134d446f0ca2d52e45f0a
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M .gitignore
    M Makefile
    M configure

  Log Message:
  -----------
  Makefile, configure: Support building rST documentation

Add support to our configure and makefile machinery for building
our rST docs into HTML files.

Building the documentation now requires that sphinx-build is
available; this seems better than allowing half the docs to
be built if it is not present but having half of them missing.
(In particular it means that assuming that distros configured with
--enable-docs they'll get a helpful error from configure telling
them the new build dependency.)

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Tested-by: Philippe Mathieu-Daudé <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 57b49737ae467fd95504de7b2d755a994e7cec4b
      
https://github.com/qemu/qemu/commit/57b49737ae467fd95504de7b2d755a994e7cec4b
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M Makefile

  Log Message:
  -----------
  Makefile: Abstract out "identify the pkgversion" code

Abstract out the "identify the pkgversion" code from the
rule for creating qemu-version.h, so it sets makefile
variables for QEMU_PKGVERSION and QEMU_FULL_VERSION.
(We will want to use these when building the Sphinx docs.)

NB: As we abstract this out, we use -e to check for .git
rather than -d, since in some situations .git may be a file
rather than a directory.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: 6038f5fca588d8f44c403a8b8742163d9ab4adba
      
https://github.com/qemu/qemu/commit/6038f5fca588d8f44c403a8b8742163d9ab4adba
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M Makefile
    M docs/conf.py

  Log Message:
  -----------
  docs/conf.py: Don't hard-code QEMU version

Don't hard-code the QEMU version number into conf.py. Instead
we either pass it to sphinx-build on the command line, or
(if doing a standalone Sphinx run in a readthedocs.org setup)
extract it from the VERSION file.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Alex Bennée <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Tested-by: Philippe Mathieu-Daudé <address@hidden>
Acked-by: Aleksandar Markovic <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden
Message-id: address@hidden


  Commit: c10e01b996df09f6cb4eceb2b7a9754bece927c9
      
https://github.com/qemu/qemu/commit/c10e01b996df09f6cb4eceb2b7a9754bece927c9
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M MAINTAINERS

  Log Message:
  -----------
  MAINTAINERS: Add entry for Sphinx documentation infrastructure

Add a MAINTAINERS entry for Sphinx documentation infrastructure:
this doesn't cover actual content, only the machinery we use to
build the docs.

Signed-off-by: Peter Maydell <address@hidden>
Reviewed-by: Philippe Mathieu-Daudé <address@hidden>
Reviewed-by: Richard Henderson <address@hidden>
Message-id: address@hidden


  Commit: 21afe115a49776aa07f4d93d22b9ad133fd183a5
      
https://github.com/qemu/qemu/commit/21afe115a49776aa07f4d93d22b9ad133fd183a5
  Author: Peter Maydell <address@hidden>
  Date:   2019-03-07 (Thu, 07 Mar 2019)

  Changed paths:
    M .gitignore
    M MAINTAINERS
    M Makefile
    M configure
    A docs/conf.py
    M docs/cpu-hotplug.rst
    A docs/devel/conf.py
    A docs/devel/index.rst
    A docs/devel/memory.rst
    R docs/devel/memory.txt
    A docs/index.rst
    A docs/interop/conf.py
    A docs/interop/index.rst

  Log Message:
  -----------
  Merge remote-tracking branch 'remotes/pmaydell/tags/pull-sphinx-20190307' 
into staging

Enable building and installing rST docs with Sphinx

# gpg: Signature made Thu 07 Mar 2019 15:05:12 GMT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "address@hidden"
# gpg: Good signature from "Peter Maydell <address@hidden>" [ultimate]
# gpg:                 aka "Peter Maydell <address@hidden>" [ultimate]
# gpg:                 aka "Peter Maydell <address@hidden>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83  15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-sphinx-20190307:
  MAINTAINERS: Add entry for Sphinx documentation infrastructure
  docs/conf.py: Don't hard-code QEMU version
  Makefile: Abstract out "identify the pkgversion" code
  Makefile, configure: Support building rST documentation
  docs: Provide separate conf.py for each manual we want
  docs/conf.py: Disable option warnings
  docs/conf.py: Don't include rST sources in HTML build
  docs/conf.py: Configure the 'alabaster' theme
  docs/conf.py: Disable unused _static directory
  docs: Commit initial files from sphinx-quickstart
  docs: Convert memory.txt to rst format
  docs/cpu-hotplug.rst: Fix rST markup issues

Signed-off-by: Peter Maydell <address@hidden>


Compare: https://github.com/qemu/qemu/compare/3a75ef6a0fe3...21afe115a497