[Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[Peter Maydell]

This patchset enables building and installing the various rST
docs we have started to accumulate in our docs/ directory.
It does this using Sphinx (which is the docs tooling that the
Linux kernel uses). The series is not trying to take us in one
giant leap to a brave new Sphinx-powered world -- it is simply
setting up a framework so that we are at least building and
shipping these documents and can gradually migrate other parts
of our documentation to it.

Changes v1->v2:
 * Added a few missing Signed-off-by lines
 * Provided a proper commit message for patch 8
 * patch 9: only add 'sphinxdocs' target to 'all' if BUILD_DOCS
   is defined (fixes building on systems without sphinx-build,
   which will now just not build the docs rather than barfing)

All patches except 9 have been reviewed.

Feedback to v1 seemed to be positive, so I propose that (assuming
no further issues found in code review) we commit this series
before softfreeze for the 4.1 release.


All the text below here is from the v1 cover letter, for context.


The approach I've used here is that we will have multiple "manuals",
as proposed by Paolo here:
  https://wiki.qemu.org/Features/Documentation
For the moment I've only created 'interop' and 'devel' as we don't
yet have any rST files for 'user', 'system' or 'specs'.

One slightly awkward mismatch between how Sphinx naturally wants
to work and our requirements is that when Sphinx generates a
documentation set all in one go it creates hyperlinks between
all the docs, they all appear in a single top level table of
contents, and so on. But for QEMU's docs we don't want to
ship the "devel" manual to end-users. I've taken an approach
suggested to me on sphinx-users
(https://www.mail-archive.com/sphinx-users@googlegroups.com/msg03224.html)
where we run Sphinx once per manual, and treat them as
entirely separate documents. The config/tooling in this patchset
also supports building everything in a single run, for compatibility
with third-party docs sites like readthedocs.org.

To see the results:

What you get in the docs/ subdir of your build directory
when you do a local build:
 http://people.linaro.org/~peter.maydell/build-dir-docs/
(follow the links to 'devel' and 'interop' for the two manuals)

What we'll ship in 'make install' in /usr/local/share/doc/qemu/
http://people.linaro.org/~peter.maydell/installed-docs/
(should be same as the build dir except we don't ship 'devel')

What you get with a standalone single-run docs build:
 http://people.linaro.org/~peter.maydell/standalone-docs/index.html

These use the default 'alabaster' theme from Sphinx. I
also experimented with the 'read_the_docs' theme, which I
do think looks nicer. Unfortunately it also requires the
docs we install to include about 3MB of TrueType font files
per manual, which is awkward licensing-wise as the TTFs are
under the Open Font License and it's not completely clear to
me that it's OK to ship those to use with a doc file that is
GPLed. Alabaster doesn't ship fonts, which sidesteps both
those problems.

Other notes:
 * this does not build the two .rst files that are directly
   in docs/ (cpu-hotplug.rst and pr-manager.rst) -- we should
   move these to whichever of the five manuals is the best place
 * I do have some prototype patches which integrate the kernel's
   kerneldoc Sphinx extension to parse doc comments in source
   code. I haven't included them here because I think the 'devel'
   manual is the lowest priority of the five. They might be
   useful if we want to try things like building documentation
   of supported machine models from in-code comments/etc, though.
 * as noted in a previous email thread, the configure changes
   now mean that building docs depends on build-sphinx being
   available, so this is a new build-dep for --enable-docs.


thanks
-- PMM


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

 configure                             |   4 +-
 Makefile                              |  78 +++++++---
 docs/conf.py                          | 215 ++++++++++++++++++++++++++
 docs/cpu-hotplug.rst                  |   2 +-
 docs/devel/conf.py                    |  15 ++
 docs/devel/index.rst                  |  21 +++
 docs/devel/{memory.txt => memory.rst} | 128 ++++++++-------
 docs/index.rst                        |  15 ++
 docs/interop/conf.py                  |  15 ++
 docs/interop/index.rst                |  18 +++
 10 files changed, 430 insertions(+), 81 deletions(-)
 create mode 100644 docs/conf.py
 create mode 100644 docs/devel/conf.py
 create mode 100644 docs/devel/index.rst
 rename docs/devel/{memory.txt => memory.rst} (85%)
 create mode 100644 docs/index.rst
 create mode 100644 docs/interop/conf.py
 create mode 100644 docs/interop/index.rst

-- 
2.20.1

[Qemu-devel] [PATCH v2 01/11] docs/cpu-hotplug.rst: Fix rST markup issues

[Peter Maydell]

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>
---
 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

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

[Philippe Mathieu-Daudé]

On 2/28/19 3:56 PM, 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.

I applied your series then revert this patch to test how failures are
handled. On rebuild nothing happend, I was worried about caching then
remember something in your cover, read it again and understood this file
is not in watched directory so not generated.

Then I moved this file in a watched dir. I see warnings are not fatal,
and from the manpage there is the '-W' option:

  sphinx-build(1)

  -W     Turn warnings into errors.
         This means that the build stops at the first warning
         and sphinx-build exits with exit status 1.

Can we use this by default, as of C warnings?

This should be our default on the CI builds anyway.

Meanwhile for this patch:
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>

> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> Reviewed-by: Alex Bennée <alex.bennee@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
>        {
> 

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

[Peter Maydell]

On Thu, 28 Feb 2019 at 16:14, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
> Then I moved this file in a watched dir. I see warnings are not fatal,
> and from the manpage there is the '-W' option:
>
>   sphinx-build(1)
>
>   -W     Turn warnings into errors.
>          This means that the build stops at the first warning
>          and sphinx-build exits with exit status 1.
>
> Can we use this by default, as of C warnings?

I didn't know about this option and it sounds like a good
idea. But we probably want to only enable it on git builds
(the same as with -Werror).

I think I'd rather add -W after this lands (so we can see if
it's generating warnings on any of our build hosts that would
cause build failure that we need to fix before enabling it).

thanks
-- PMM

[Qemu-devel] [PATCH v2 02/11] docs: Convert memory.txt to rst format

[Peter Maydell]

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 <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/devel/{memory.txt => memory.rst} | 128 ++++++++++++++------------
 1 file changed, 70 insertions(+), 58 deletions(-)
 rename docs/devel/{memory.txt => memory.rst} (85%)

diff --git a/docs/devel/memory.txt b/docs/devel/memory.rst
similarity index 85%
rename from docs/devel/memory.txt
rename to docs/devel/memory.rst
index 42577e1d860..b6a4c37ea5e 100644
--- a/docs/devel/memory.txt
+++ b/docs/devel/memory.rst
@@ -1,19 +1,20 @@
+==============
 The memory API
 ==============
 
 The memory API models the memory and I/O buses and controllers of a QEMU
 machine.  It attempts to allow modelling of:
 
- - ordinary RAM
- - memory-mapped I/O (MMIO)
- - memory controllers that can dynamically reroute physical memory regions
-   to different destinations
+- ordinary RAM
+- memory-mapped I/O (MMIO)
+- memory controllers that can dynamically reroute physical memory regions
+  to different destinations
 
 The memory model provides support for
 
- - tracking RAM changes by the guest
- - setting up coalesced memory for kvm
- - setting up ioeventfd regions for kvm
+- tracking RAM changes by the guest
+- setting up coalesced memory for kvm
+- setting up ioeventfd regions for kvm
 
 Memory is modelled as an acyclic graph of MemoryRegion objects.  Sinks
 (leaves) are RAM and MMIO regions, while other nodes represent
@@ -98,25 +99,30 @@ ROM device memory region types), this host memory needs to be
 copied to the destination on migration. These APIs which allocate
 the host memory for you will also register the memory so it is
 migrated:
- - memory_region_init_ram()
- - memory_region_init_rom()
- - memory_region_init_rom_device()
+
+- memory_region_init_ram()
+- memory_region_init_rom()
+- memory_region_init_rom_device()
 
 For most devices and boards this is the correct thing. If you
 have a special case where you need to manage the migration of
 the backing memory yourself, you can call the functions:
- - memory_region_init_ram_nomigrate()
- - memory_region_init_rom_nomigrate()
- - memory_region_init_rom_device_nomigrate()
+
+- memory_region_init_ram_nomigrate()
+- memory_region_init_rom_nomigrate()
+- memory_region_init_rom_device_nomigrate()
+
 which only initialize the MemoryRegion and leave handling
 migration to the caller.
 
 The functions:
- - memory_region_init_resizeable_ram()
- - memory_region_init_ram_from_file()
- - memory_region_init_ram_from_fd()
- - memory_region_init_ram_ptr()
- - memory_region_init_ram_device_ptr()
+
+- memory_region_init_resizeable_ram()
+- memory_region_init_ram_from_file()
+- memory_region_init_ram_from_fd()
+- memory_region_init_ram_ptr()
+- memory_region_init_ram_device_ptr()
+
 are for special cases only, and so they do not automatically
 register the backing memory for migration; the caller must
 manage migration if necessary.
@@ -218,7 +224,7 @@ For example, suppose we have a container A of size 0x8000 with two subregions
 B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is
 an MMIO region mapped at 0x0, size 0x6000, priority 1. B currently has two
 of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at
-offset 0x2000. As a diagram:
+offset 0x2000. As a diagram::
 
         0      1000   2000   3000   4000   5000   6000   7000   8000
         |------|------|------|------|------|------|------|------|
@@ -228,8 +234,9 @@ offset 0x2000. As a diagram:
   D:                  [DDDDD]
   E:                                [EEEEE]
 
-The regions that will be seen within this address range then are:
-        [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC]
+The regions that will be seen within this address range then are::
+
+  [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC]
 
 Since B has higher priority than C, its subregions appear in the flat map
 even where they overlap with C. In ranges where B has not mapped anything
@@ -237,8 +244,9 @@ C's region appears.
 
 If B had provided its own MMIO operations (ie it was not a pure container)
 then these would be used for any addresses in its range not handled by
-D or E, and the result would be:
-        [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB]
+D or E, and the result would be::
+
+  [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB]
 
 Priority values are local to a container, because the priorities of two
 regions are only compared when they are both children of the same container.
@@ -257,6 +265,7 @@ guest accesses an address:
 
 - all direct subregions of the root region are matched against the address, in
   descending priority order
+
   - if the address lies outside the region offset/size, the subregion is
     discarded
   - if the subregion is a leaf (RAM or MMIO), the search terminates, returning
@@ -270,36 +279,39 @@ guest accesses an address:
     address range), then if this is a container with its own MMIO or RAM
     backing the search terminates, returning the container itself. Otherwise
     we continue with the next subregion in priority order
+
 - if none of the subregions match the address then the search terminates
   with no match found
 
 Example memory map
 ------------------
 
-system_memory: container@0-2^48-1
- |
- +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff)
- |
- +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff)
- |
- +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff)
- |      (prio 1)
- |
- +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff)
+::
 
-pci (0-2^32-1)
- |
- +--- vga-area: container@0xa0000-0xbffff
- |      |
- |      +--- alias@0x00000-0x7fff  ---> #vram (0x010000-0x017fff)
- |      |
- |      +--- alias@0x08000-0xffff  ---> #vram (0x020000-0x027fff)
- |
- +---- vram: ram@0xe1000000-0xe1ffffff
- |
- +---- vga-mmio: mmio@0xe2000000-0xe200ffff
+  system_memory: container@0-2^48-1
+   |
+   +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff)
+   |
+   +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff)
+   |
+   +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff)
+   |      (prio 1)
+   |
+   +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff)
 
-ram: ram@0x00000000-0xffffffff
+  pci (0-2^32-1)
+   |
+   +--- vga-area: container@0xa0000-0xbffff
+   |      |
+   |      +--- alias@0x00000-0x7fff  ---> #vram (0x010000-0x017fff)
+   |      |
+   |      +--- alias@0x08000-0xffff  ---> #vram (0x020000-0x027fff)
+   |
+   +---- vram: ram@0xe1000000-0xe1ffffff
+   |
+   +---- vga-mmio: mmio@0xe2000000-0xe200ffff
+
+  ram: ram@0x00000000-0xffffffff
 
 This is a (simplified) PC memory map. The 4GB RAM block is mapped into the
 system address space via two aliases: "lomem" is a 1:1 mapping of the first
@@ -336,16 +348,16 @@ rather than completing successfully; those devices can use the
 In addition various constraints can be supplied to control how these
 callbacks are called:
 
- - .valid.min_access_size, .valid.max_access_size define the access sizes
-   (in bytes) which the device accepts; accesses outside this range will
-   have device and bus specific behaviour (ignored, or machine check)
- - .valid.unaligned specifies that the *device being modelled* supports
-    unaligned accesses; if false, unaligned accesses will invoke the
-    appropriate bus or CPU specific behaviour.
- - .impl.min_access_size, .impl.max_access_size define the access sizes
-   (in bytes) supported by the *implementation*; other access sizes will be
-   emulated using the ones available.  For example a 4-byte write will be
-   emulated using four 1-byte writes, if .impl.max_access_size = 1.
- - .impl.unaligned specifies that the *implementation* supports unaligned
-   accesses; if false, unaligned accesses will be emulated by two aligned
-   accesses.
+- .valid.min_access_size, .valid.max_access_size define the access sizes
+  (in bytes) which the device accepts; accesses outside this range will
+  have device and bus specific behaviour (ignored, or machine check)
+- .valid.unaligned specifies that the *device being modelled* supports
+  unaligned accesses; if false, unaligned accesses will invoke the
+  appropriate bus or CPU specific behaviour.
+- .impl.min_access_size, .impl.max_access_size define the access sizes
+  (in bytes) supported by the *implementation*; other access sizes will be
+  emulated using the ones available.  For example a 4-byte write will be
+  emulated using four 1-byte writes, if .impl.max_access_size = 1.
+- .impl.unaligned specifies that the *implementation* supports unaligned
+  accesses; if false, unaligned accesses will be emulated by two aligned
+  accesses.
-- 
2.20.1

[Qemu-devel] [PATCH v2 03/11] docs: Commit initial files from sphinx-quickstart

[Peter Maydell]

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 <peter.maydell@linaro.org>
---
 docs/conf.py   | 168 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst |  20 ++++++
 2 files changed, 188 insertions(+)
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst

diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 00000000000..53a17506615
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+#
+# QEMU documentation build configuration file, created by
+# sphinx-quickstart on Thu Jan 31 16:40:14 2019.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'QEMU'
+copyright = u'2019, The QEMU Project Developers'
+author = u'The QEMU Project Developers'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'4.0'
+# The full version, including alpha/beta/rc tags.
+release = u'4.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'QEMUdoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'QEMU.tex', u'QEMU Documentation',
+     u'The QEMU Project Developers', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'qemu', u'QEMU Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'QEMU', u'QEMU Documentation',
+     author, 'QEMU', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 00000000000..93f82228310
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,20 @@
+.. QEMU documentation master file, created by
+   sphinx-quickstart on Thu Jan 31 16:40:14 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to QEMU's documentation!
+================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
-- 
2.20.1

Re: [Qemu-devel] [PATCH v2 03/11] docs: Commit initial files from sphinx-quickstart

[Philippe Mathieu-Daudé]

Hi Peter,

On 2/28/19 3:56 PM, Peter Maydell wrote:
> 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 <peter.maydell@linaro.org>
> ---
>  docs/conf.py   | 168 +++++++++++++++++++++++++++++++++++++++++++++++++

Can you add a "rST documentation" section in MAINTAINERS?

Eduardo/Cleber:

What about replacing the current resctricted rules in the "Python
scripts" section by a global "F: *.py" rule?

Thanks,

Phil.

>  docs/index.rst |  20 ++++++
>  2 files changed, 188 insertions(+)
>  create mode 100644 docs/conf.py
>  create mode 100644 docs/index.rst
> 
> diff --git a/docs/conf.py b/docs/conf.py
> new file mode 100644
> index 00000000000..53a17506615
> --- /dev/null
> +++ b/docs/conf.py
> @@ -0,0 +1,168 @@
> +# -*- coding: utf-8 -*-
> +#
> +# QEMU documentation build configuration file, created by
> +# sphinx-quickstart on Thu Jan 31 16:40:14 2019.
> +#
> +# This file is execfile()d with the current directory set to its
> +# containing dir.
> +#
> +# Note that not all possible configuration values are present in this
> +# autogenerated file.
> +#
> +# All configuration values have a default; values that are commented out
> +# serve to show the default.
> +
> +# If extensions (or modules to document with autodoc) are in another directory,
> +# add these directories to sys.path here. If the directory is relative to the
> +# documentation root, use os.path.abspath to make it absolute, like shown here.
> +#
> +# import os
> +# import sys
> +# sys.path.insert(0, os.path.abspath('.'))
> +
> +
> +# -- General configuration ------------------------------------------------
> +
> +# If your documentation needs a minimal Sphinx version, state it here.
> +#
> +# needs_sphinx = '1.0'
> +
> +# Add any Sphinx extension module names here, as strings. They can be
> +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
> +# ones.
> +extensions = []
> +
> +# Add any paths that contain templates here, relative to this directory.
> +templates_path = ['_templates']
> +
> +# The suffix(es) of source filenames.
> +# You can specify multiple suffix as a list of string:
> +#
> +# source_suffix = ['.rst', '.md']
> +source_suffix = '.rst'
> +
> +# The master toctree document.
> +master_doc = 'index'
> +
> +# General information about the project.
> +project = u'QEMU'
> +copyright = u'2019, The QEMU Project Developers'
> +author = u'The QEMU Project Developers'
> +
> +# The version info for the project you're documenting, acts as replacement for
> +# |version| and |release|, also used in various other places throughout the
> +# built documents.
> +#
> +# The short X.Y version.
> +version = u'4.0'
> +# The full version, including alpha/beta/rc tags.
> +release = u'4.0'
> +
> +# The language for content autogenerated by Sphinx. Refer to documentation
> +# for a list of supported languages.
> +#
> +# This is also used if you do content translation via gettext catalogs.
> +# Usually you set "language" from the command line for these cases.
> +language = None
> +
> +# List of patterns, relative to source directory, that match files and
> +# directories to ignore when looking for source files.
> +# This patterns also effect to html_static_path and html_extra_path
> +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
> +
> +# The name of the Pygments (syntax highlighting) style to use.
> +pygments_style = 'sphinx'
> +
> +# If true, `todo` and `todoList` produce output, else they produce nothing.
> +todo_include_todos = False
> +
> +
> +# -- Options for HTML output ----------------------------------------------
> +
> +# The theme to use for HTML and HTML Help pages.  See the documentation for
> +# a list of builtin themes.
> +#
> +html_theme = 'alabaster'
> +
> +# Theme options are theme-specific and customize the look and feel of a theme
> +# further.  For a list of options available for each theme, see the
> +# documentation.
> +#
> +# html_theme_options = {}
> +
> +# Add any paths that contain custom static files (such as style sheets) here,
> +# relative to this directory. They are copied after the builtin static files,
> +# so a file named "default.css" will overwrite the builtin "default.css".
> +html_static_path = ['_static']
> +
> +# Custom sidebar templates, must be a dictionary that maps document names
> +# to template names.
> +#
> +# This is required for the alabaster theme
> +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
> +html_sidebars = {
> +    '**': [
> +        'relations.html',  # needs 'show_related': True theme option to display
> +        'searchbox.html',
> +    ]
> +}
> +
> +
> +# -- Options for HTMLHelp output ------------------------------------------
> +
> +# Output file base name for HTML help builder.
> +htmlhelp_basename = 'QEMUdoc'
> +
> +
> +# -- Options for LaTeX output ---------------------------------------------
> +
> +latex_elements = {
> +    # The paper size ('letterpaper' or 'a4paper').
> +    #
> +    # 'papersize': 'letterpaper',
> +
> +    # The font size ('10pt', '11pt' or '12pt').
> +    #
> +    # 'pointsize': '10pt',
> +
> +    # Additional stuff for the LaTeX preamble.
> +    #
> +    # 'preamble': '',
> +
> +    # Latex figure (float) alignment
> +    #
> +    # 'figure_align': 'htbp',
> +}
> +
> +# Grouping the document tree into LaTeX files. List of tuples
> +# (source start file, target name, title,
> +#  author, documentclass [howto, manual, or own class]).
> +latex_documents = [
> +    (master_doc, 'QEMU.tex', u'QEMU Documentation',
> +     u'The QEMU Project Developers', 'manual'),
> +]
> +
> +
> +# -- Options for manual page output ---------------------------------------
> +
> +# One entry per manual page. List of tuples
> +# (source start file, name, description, authors, manual section).
> +man_pages = [
> +    (master_doc, 'qemu', u'QEMU Documentation',
> +     [author], 1)
> +]
> +
> +
> +# -- Options for Texinfo output -------------------------------------------
> +
> +# Grouping the document tree into Texinfo files. List of tuples
> +# (source start file, target name, title, author,
> +#  dir menu entry, description, category)
> +texinfo_documents = [
> +    (master_doc, 'QEMU', u'QEMU Documentation',
> +     author, 'QEMU', 'One line description of project.',
> +     'Miscellaneous'),
> +]
> +
> +
> +
> diff --git a/docs/index.rst b/docs/index.rst
> new file mode 100644
> index 00000000000..93f82228310
> --- /dev/null
> +++ b/docs/index.rst
> @@ -0,0 +1,20 @@
> +.. QEMU documentation master file, created by
> +   sphinx-quickstart on Thu Jan 31 16:40:14 2019.
> +   You can adapt this file completely to your liking, but it should at least
> +   contain the root `toctree` directive.
> +
> +Welcome to QEMU's documentation!
> +================================
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :caption: Contents:
> +
> +
> +
> +Indices and tables
> +==================
> +
> +* :ref:`genindex`
> +* :ref:`modindex`
> +* :ref:`search`
> 

Re: [Qemu-devel] [PATCH v2 03/11] docs: Commit initial files from sphinx-quickstart

[Peter Maydell]

On Thu, 28 Feb 2019 at 16:01, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>
> Hi Peter,
>
> On 2/28/19 3:56 PM, Peter Maydell wrote:
> > 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 <peter.maydell@linaro.org>
> > ---
> >  docs/conf.py   | 168 +++++++++++++++++++++++++++++++++++++++++++++++++
>
> Can you add a "rST documentation" section in MAINTAINERS?

We don't have documentation listed in a separate section --
individual doc files get listed under the section of the
code they're documenting, because the maintainers are
different for each doc.

I was thinking about maybe having a section for the
Sphinx doc build infrastructure itself, but wasn't
sure what it should list.

thanks
-- PMM

[Qemu-devel] [PATCH v2 04/11] docs/conf.py: Disable unused _static directory

[Peter Maydell]

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 <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/conf.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 53a17506615..e1d08a34a65 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -93,7 +93,11 @@ html_theme = 'alabaster'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# QEMU doesn't yet have any static files, so comment this out so we don't
+# get a warning about a missing directory.
+# If we do ever add this then it would probably be better to call the
+# subdirectory sphinx_static, as the Linux kernel does.
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
-- 
2.20.1

[Qemu-devel] [PATCH v2 05/11] docs/conf.py: Configure the 'alabaster' theme

[Peter Maydell]

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.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/conf.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index e1d08a34a65..348e6358740 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -106,7 +106,8 @@ html_theme = 'alabaster'
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
     '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
+        'about.html',
+        'navigation.html',
         'searchbox.html',
     ]
 }
-- 
2.20.1

[Qemu-devel] [PATCH v2 06/11] docs/conf.py: Don't include rST sources in HTML build

[Peter Maydell]

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 <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 348e6358740..6ddaa549f28 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -112,6 +112,9 @@ html_sidebars = {
     ]
 }
 
+# Don't copy the rST source files to the HTML output directory,
+# and don't put links to the sources into the output HTML.
+html_copy_source = False
 
 # -- Options for HTMLHelp output ------------------------------------------
 
-- 
2.20.1

[Qemu-devel] [PATCH v2 07/11] docs/conf.py: Disable option warnings

[Peter Maydell]

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 <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 6ddaa549f28..c04000e78e4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -76,6 +76,9 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# Sphinx defaults to warning about use of :option: for options not defined
+# with "option::" in the document being processed. Turn that off.
+suppress_warnings = ["ref.option"]
 
 # -- Options for HTML output ----------------------------------------------
 
-- 
2.20.1

[Qemu-devel] [PATCH v2 08/11] docs: Provide separate conf.py for each manual we want

[Peter Maydell]

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 <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/conf.py           | 37 +++++++++++++++++++++++++++++++------
 docs/devel/conf.py     | 15 +++++++++++++++
 docs/devel/index.rst   | 21 +++++++++++++++++++++
 docs/index.rst         |  9 ++-------
 docs/interop/conf.py   | 15 +++++++++++++++
 docs/interop/index.rst | 18 ++++++++++++++++++
 6 files changed, 102 insertions(+), 13 deletions(-)
 create mode 100644 docs/devel/conf.py
 create mode 100644 docs/devel/index.rst
 create mode 100644 docs/interop/conf.py
 create mode 100644 docs/interop/index.rst

diff --git a/docs/conf.py b/docs/conf.py
index c04000e78e4..6a334f545ec 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -3,6 +3,20 @@
 # QEMU documentation build configuration file, created by
 # sphinx-quickstart on Thu Jan 31 16:40:14 2019.
 #
+# This config file can be used in one of two ways:
+# (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.
+#
+# QEMU's makefiles take option (1), which allows us to install
+# only the ones the user cares about (in particular we don't want
+# to ship the 'devel' manual to end-users).
+# Third-party sites such as readthedocs.org will take option (2).
+#
+#
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
@@ -12,13 +26,22 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import os
+import sys
+
+# The per-manual conf.py will set qemu_docdir for a single-manual build;
+# otherwise set it here if this is an entire-manual-set build.
+# This is always the absolute path of the docs/ directory in the source tree.
+try:
+    qemu_docdir
+except NameError:
+    qemu_docdir = os.path.abspath(".")
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
+# documentation root, use an absolute path starting from qemu_docdir.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir"))
 
 
 # -- General configuration ------------------------------------------------
@@ -90,8 +113,10 @@ html_theme = 'alabaster'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-# html_theme_options = {}
+# We initialize this to empty here, so the per-manual conf.py can just
+# add individual key/value entries.
+html_theme_options = {
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/docs/devel/conf.py b/docs/devel/conf.py
new file mode 100644
index 00000000000..7441f87e7f5
--- /dev/null
+++ b/docs/devel/conf.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+#
+# QEMU documentation build configuration file for the 'devel' manual.
+#
+# This includes the top level conf file and then makes any necessary tweaks.
+import sys
+import os
+
+qemu_docdir = os.path.abspath("..")
+parent_config = os.path.join(qemu_docdir, "conf.py")
+exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
+
+# This slightly misuses the 'description', but is the best way to get
+# the manual title to appear in the sidebar.
+html_theme_options['description'] = u'Developer''s Guide'
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
new file mode 100644
index 00000000000..cd0fa6c9ba2
--- /dev/null
+++ b/docs/devel/index.rst
@@ -0,0 +1,21 @@
+.. This is the top level page for the 'devel' manual.
+
+
+QEMU Developer's Guide
+======================
+
+This manual documents various parts of the internals of QEMU.
+You only need to read it if you are interested in reading or
+modifying QEMU's source code.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   loads-stores
+   memory
+   migration
+   stable-process
+   testing
+
diff --git a/docs/index.rst b/docs/index.rst
index 93f82228310..3690955dd1f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,11 +10,6 @@ Welcome to QEMU's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   interop/index
+   devel/index
 
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
new file mode 100644
index 00000000000..cf3c69d4a7e
--- /dev/null
+++ b/docs/interop/conf.py
@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+#
+# QEMU documentation build configuration file for the 'interop' manual.
+#
+# This includes the top level conf file and then makes any necessary tweaks.
+import sys
+import os
+
+qemu_docdir = os.path.abspath("..")
+parent_config = os.path.join(qemu_docdir, "conf.py")
+exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
+
+# This slightly misuses the 'description', but is the best way to get
+# the manual title to appear in the sidebar.
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
new file mode 100644
index 00000000000..2df977dd529
--- /dev/null
+++ b/docs/interop/index.rst
@@ -0,0 +1,18 @@
+.. This is the top level page for the 'interop' manual.
+
+
+QEMU System Emulation Management and Interoperability Guide
+===========================================================
+
+This manual contains documents and specifications that are useful
+for making QEMU interoperate with other software.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   bitmaps
+   live-block-operations
+   pr-helper
+
-- 
2.20.1

[Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Peter Maydell]

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 <peter.maydell@linaro.org>
---
 configure |  4 ++--
 Makefile  | 45 ++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/configure b/configure
index 694088a4ec9..bf6850d4bd9 100755
--- a/configure
+++ b/configure
@@ -4565,11 +4565,11 @@ fi
 
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has makeinfo && has pod2man; then
+  if has makeinfo && has pod2man && has sphinx-build; then
     docs=yes
   else
     if test "$docs" = "yes" ; then
-      feature_not_found "docs" "Install texinfo and Perl/perl-podlators"
+      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"
     fi
     docs=no
   fi
diff --git a/Makefile b/Makefile
index 7fa04e08212..d6b897be0bc 100644
--- a/Makefile
+++ b/Makefile
@@ -388,7 +388,7 @@ dummy := $(call unnest-vars,, \
 
 include $(SRC_PATH)/tests/Makefile.include
 
-all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
+all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules
 
 qemu-version.h: FORCE
 	$(call quiet-command, \
@@ -633,6 +633,14 @@ dist: qemu-$(VERSION).tar.bz2
 qemu-%.tar.bz2:
 	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
 
+# Note that these commands assume that there are no HTML files in
+# the docs subdir in the source tree! If there are then this will
+# blow them away for an in-source-tree 'make clean'.
+define clean-manual =
+rm -rf docs/$1/_static
+rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html
+endef
+
 distclean: clean
 	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
 	rm -f config-all-devices.mak config-all-disas.mak config.status
@@ -653,6 +661,9 @@ distclean: clean
 	rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
 	rm -f docs/qemu-block-drivers.7
 	rm -f docs/qemu-cpu-models.7
+	rm -f .doctrees
+	$(call clean-manual,devel)
+	$(call clean-manual,interop)
 	for d in $(TARGET_DIRS); do \
 	rm -rf $$d || exit 1 ; \
         done
@@ -686,7 +697,18 @@ else
 BLOBS=
 endif
 
-install-doc: $(DOCS)
+define install-manual =
+for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
+for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
+endef
+
+# Note that we deliberately do not install the "devel" manual: it is
+# for QEMU developers, and not interesting to our users.
+.PHONY: install-sphinxdocs
+install-sphinxdocs: sphinxdocs
+	$(call install-manual,interop)
+
+install-doc: $(DOCS) install-sphinxdocs
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
@@ -837,6 +859,23 @@ docs/version.texi: $(SRC_PATH)/VERSION
 %.pdf: %.texi docs/version.texi
 	$(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@")
 
+# Sphinx builds all its documentation at once in one invocation
+# and handles "don't rebuild things unless necessary" itself.
+# The '.doctrees' files are cached information to speed this up.
+.PHONY: sphinxdocs
+sphinxdocs: docs/devel/index.html docs/interop/index.html
+
+# Canned command to build a single manual
+build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
+# We assume all RST files in the manual's directory are used in it
+manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
+
+docs/devel/index.html: $(call manual-deps,devel)
+	$(call build-manual,devel)
+
+docs/interop/index.html: $(call manual-deps,interop)
+	$(call build-manual,interop)
+
 qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
 
@@ -865,7 +904,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
 docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
 scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
 
-html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
+html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
 info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
 pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
 txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
-- 
2.20.1

Re: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Philippe Mathieu-Daudé]

Hi Peter,

On 2/28/19 3:56 PM, Peter Maydell wrote:
> 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 <peter.maydell@linaro.org>
> ---
>  configure |  4 ++--
>  Makefile  | 45 ++++++++++++++++++++++++++++++++++++++++++---
>  2 files changed, 44 insertions(+), 5 deletions(-)
> 
> diff --git a/configure b/configure
> index 694088a4ec9..bf6850d4bd9 100755
> --- a/configure
> +++ b/configure
> @@ -4565,11 +4565,11 @@ fi
>  
>  # Check if tools are available to build documentation.
>  if test "$docs" != "no" ; then
> -  if has makeinfo && has pod2man; then
> +  if has makeinfo && has pod2man && has sphinx-build; then

Unrelated to your patch, I tried that on fresh Fedora image where no
python2 installed (on purpose). sphinx-build is not included in the
suggested python3-sphinx. Once python2-sphinx installed (which pull a
lot of py2 packages) I could test your series.

>      docs=yes
>    else
>      if test "$docs" = "yes" ; then
> -      feature_not_found "docs" "Install texinfo and Perl/perl-podlators"
> +      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"
>      fi
>      docs=no
>    fi
> diff --git a/Makefile b/Makefile
> index 7fa04e08212..d6b897be0bc 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -388,7 +388,7 @@ dummy := $(call unnest-vars,, \
>  
>  include $(SRC_PATH)/tests/Makefile.include
>  
> -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
> +all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules
>  
>  qemu-version.h: FORCE
>  	$(call quiet-command, \
> @@ -633,6 +633,14 @@ dist: qemu-$(VERSION).tar.bz2
>  qemu-%.tar.bz2:
>  	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
>  
> +# Note that these commands assume that there are no HTML files in
> +# the docs subdir in the source tree! If there are then this will
> +# blow them away for an in-source-tree 'make clean'.
> +define clean-manual =
> +rm -rf docs/$1/_static
> +rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html
> +endef
> +
>  distclean: clean
>  	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
>  	rm -f config-all-devices.mak config-all-disas.mak config.status
> @@ -653,6 +661,9 @@ distclean: clean
>  	rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
>  	rm -f docs/qemu-block-drivers.7
>  	rm -f docs/qemu-cpu-models.7
> +	rm -f .doctrees
> +	$(call clean-manual,devel)
> +	$(call clean-manual,interop)
>  	for d in $(TARGET_DIRS); do \
>  	rm -rf $$d || exit 1 ; \
>          done
> @@ -686,7 +697,18 @@ else
>  BLOBS=
>  endif
>  
> -install-doc: $(DOCS)
> +define install-manual =
> +for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
> +for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
> +endef
> +
> +# Note that we deliberately do not install the "devel" manual: it is
> +# for QEMU developers, and not interesting to our users.
> +.PHONY: install-sphinxdocs
> +install-sphinxdocs: sphinxdocs
> +	$(call install-manual,interop)

Again, not related to your patch, but 'make install-sphinxdocs' clone
libfdt + capstone, requires C compiler to build libfdt.a and C++ to
build libcapstone.a. Once both build we can generate the doc.

> +
> +install-doc: $(DOCS) install-sphinxdocs
>  	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
> @@ -837,6 +859,23 @@ docs/version.texi: $(SRC_PATH)/VERSION
>  %.pdf: %.texi docs/version.texi
>  	$(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@")
>  
> +# Sphinx builds all its documentation at once in one invocation
> +# and handles "don't rebuild things unless necessary" itself.
> +# The '.doctrees' files are cached information to speed this up.

Can you add .doctrees to .gitignore?

> +.PHONY: sphinxdocs
> +sphinxdocs: docs/devel/index.html docs/interop/index.html
> +
> +# Canned command to build a single manual
> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
> +# We assume all RST files in the manual's directory are used in it
> +manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
> +
> +docs/devel/index.html: $(call manual-deps,devel)
> +	$(call build-manual,devel)
> +
> +docs/interop/index.html: $(call manual-deps,interop)
> +	$(call build-manual,interop)
> +
>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
>  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
>  
> @@ -865,7 +904,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
>  docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
>  scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
>  
> -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
> +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
>  info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
>  pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
>  txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
> 

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Thanks,

Phil.

Re: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Peter Maydell]

On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>
> Hi Peter,
>
> On 2/28/19 3:56 PM, Peter Maydell wrote:
> >  if test "$docs" != "no" ; then
> > -  if has makeinfo && has pod2man; then
> > +  if has makeinfo && has pod2man && has sphinx-build; then
>
> Unrelated to your patch, I tried that on fresh Fedora image where no
> python2 installed (on purpose). sphinx-build is not included in the
> suggested python3-sphinx. Once python2-sphinx installed (which pull a
> lot of py2 packages) I could test your series.

Yeah, Fedora gives the Python 3 version of the tool a silly name.
I'm told newer Fedora fix this.

> Again, not related to your patch, but 'make install-sphinxdocs' clone
> libfdt + capstone, requires C compiler to build libfdt.a and C++ to
> build libcapstone.a. Once both build we can generate the doc.

Yes, this sounds like an unrelated thing -- our makefiles
sometimes does more work than you expect because of some
things that we do up front (like building anything in
GENERATED_FILES, or doing this subdirs stuff). You can see
that sometimes when you do 'make clean' and it builds a
bunch of stuff before deleting it.

> > +# Sphinx builds all its documentation at once in one invocation
> > +# and handles "don't rebuild things unless necessary" itself.
> > +# The '.doctrees' files are cached information to speed this up.
>
> Can you add .doctrees to .gitignore?

Sure. I tend to forget about this because I never do in-tree
builds, so anything in the build directory doesn't show up
in git status separately.

> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Thanks for the review.

-- PMM

Re: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Peter Maydell]

On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>
> Hi Peter,
>
> On 2/28/19 3:56 PM, Peter Maydell wrote:
> > +# Sphinx builds all its documentation at once in one invocation
> > +# and handles "don't rebuild things unless necessary" itself.
> > +# The '.doctrees' files are cached information to speed this up.
>
> Can you add .doctrees to .gitignore?

Since this was the only change request for this patchset,
I plan to send out a pullreq containing it, with this folded
into this patch:

diff --git a/.gitignore b/.gitignore
index b66b7725512..77522561b8e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+/.doctrees
 /config-devices.*
 /config-all-devices.*
 /config-all-disas.*

thanks
-- PMM

Re: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Peter Maydell]

On Tue, 5 Mar 2019 at 12:47, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
> >
> > Hi Peter,
> >
> > On 2/28/19 3:56 PM, Peter Maydell wrote:
> > > +# Sphinx builds all its documentation at once in one invocation
> > > +# and handles "don't rebuild things unless necessary" itself.
> > > +# The '.doctrees' files are cached information to speed this up.
> >
> > Can you add .doctrees to .gitignore?
>
> Since this was the only change request for this patchset,
> I plan to send out a pullreq containing it, with this folded
> into this patch:
>
> diff --git a/.gitignore b/.gitignore
> index b66b7725512..77522561b8e 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -1,3 +1,4 @@
> +/.doctrees
>  /config-devices.*
>  /config-all-devices.*
>  /config-all-disas.*

Testing on various hosts revealed that we have a problem on
hosts with ancient versions of sphinx that predate the 'alabaster'
theme, so the configure test needs to be smarter. The fixup is
the change below.

Are people OK with me squashing this in too, or have we
reached the point where it really ought to have a v3 sent out ?


diff --git a/configure b/configure
index f1f028340aa..47bf617fcc5 100755
--- a/configure
+++ b/configure
@@ -4589,9 +4589,20 @@ if compile_prog "" "" ; then
   syncfs=yes
 fi

+# Check we have a new enough version of sphinx-build
+has_sphinx_build() {
+    # This is a bit awkward but works: create a trivial document and
+    # try to run it with our configuration file (which enforces a
+    # version requirement). This will fail if either
+    # sphinx-build doesn't exist at all or if it is too old.
+    mkdir -p "$TMPDIR1/sphinx"
+    touch "$TMPDIR1/sphinx/index.rst"
+    sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx"
"$TMPDIR1/sphinx/out" >/dev/null 2>&1
+}
+
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has makeinfo && has pod2man && has sphinx-build; then
+  if has makeinfo && has pod2man && has_sphinx_build; then
     docs=yes
   else
     if test "$docs" = "yes" ; then
diff --git a/docs/conf.py b/docs/conf.py
index 0842d44e930..befbcc6c3e1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -48,7 +48,8 @@ except NameError:

 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+# 1.3 is where the 'alabaster' theme was shipped with Sphinx.
+needs_sphinx = '1.3'

 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom


thanks
-- PMM

Re: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation

[Paolo Bonzini]

On 05/03/19 16:24, Peter Maydell wrote:
> On Tue, 5 Mar 2019 at 12:47, Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> On Thu, 28 Feb 2019 at 15:49, Philippe Mathieu-Daudé <philmd@redhat.com> wrote:
>>>
>>> Hi Peter,
>>>
>>> On 2/28/19 3:56 PM, Peter Maydell wrote:
>>>> +# Sphinx builds all its documentation at once in one invocation
>>>> +# and handles "don't rebuild things unless necessary" itself.
>>>> +# The '.doctrees' files are cached information to speed this up.
>>>
>>> Can you add .doctrees to .gitignore?
>>
>> Since this was the only change request for this patchset,
>> I plan to send out a pullreq containing it, with this folded
>> into this patch:
>>
>> diff --git a/.gitignore b/.gitignore
>> index b66b7725512..77522561b8e 100644
>> --- a/.gitignore
>> +++ b/.gitignore
>> @@ -1,3 +1,4 @@
>> +/.doctrees
>>  /config-devices.*
>>  /config-all-devices.*
>>  /config-all-disas.*
> 
> Testing on various hosts revealed that we have a problem on
> hosts with ancient versions of sphinx that predate the 'alabaster'
> theme, so the configure test needs to be smarter. The fixup is
> the change below.
> 
> Are people OK with me squashing this in too, or have we
> reached the point where it really ought to have a v3 sent out ?

Nah, go ahead.

Paolo

[Qemu-devel] [PATCH v2 10/11] Makefile: Abstract out "identify the pkgversion" code

[Peter Maydell]

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.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 Makefile | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/Makefile b/Makefile
index d6b897be0bc..46cb8e62571 100644
--- a/Makefile
+++ b/Makefile
@@ -87,6 +87,20 @@ endif
 
 include $(SRC_PATH)/rules.mak
 
+# Create QEMU_PKGVERSION and FULL_VERSION strings
+# If PKGVERSION is set, use that; otherwise get version and -dirty status from git
+QEMU_PKGVERSION := $(if $(PKGVERSION),$(PKGVERSION),$(shell \
+  cd $(SRC_PATH); \
+  if test -d .git; then \
+    git describe --match 'v*' 2>/dev/null | tr -d '\n'; \
+    if ! git diff-index --quiet HEAD &>/dev/null; then \
+      echo "-dirty"; \
+    fi; \
+  fi))
+
+# Either "version (pkgversion)", or just "version" if pkgversion not set
+FULL_VERSION := $(if $(QEMU_PKGVERSION),$(VERSION) ($(QEMU_PKGVERSION)),$(VERSION))
+
 GENERATED_FILES = qemu-version.h config-host.h qemu-options.def
 
 GENERATED_QAPI_FILES = qapi/qapi-builtin-types.h qapi/qapi-builtin-types.c
@@ -392,23 +406,8 @@ all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all mo
 
 qemu-version.h: FORCE
 	$(call quiet-command, \
-		(cd $(SRC_PATH); \
-		if test -n "$(PKGVERSION)"; then \
-			pkgvers="$(PKGVERSION)"; \
-		else \
-			if test -d .git; then \
-				pkgvers=$$(git describe --match 'v*' 2>/dev/null | tr -d '\n');\
-				if ! git diff-index --quiet HEAD &>/dev/null; then \
-					pkgvers="$${pkgvers}-dirty"; \
-				fi; \
-			fi; \
-		fi; \
-		printf "#define QEMU_PKGVERSION \"$${pkgvers}\"\n"; \
-		if test -n "$${pkgvers}"; then \
-			printf '#define QEMU_FULL_VERSION QEMU_VERSION " (" QEMU_PKGVERSION ")"\n'; \
-		else \
-			printf '#define QEMU_FULL_VERSION QEMU_VERSION\n'; \
-		fi; \
+                (printf '#define QEMU_PKGVERSION "$(QEMU_PKGVERSION)"\n'; \
+		printf '#define QEMU_FULL_VERSION "$(FULL_VERSION)"\n'; \
 		) > $@.tmp)
 	$(call quiet-command, if ! cmp -s $@ $@.tmp; then \
 	  mv $@.tmp $@; \
-- 
2.20.1

[Qemu-devel] [PATCH v2 11/11] docs/conf.py: Don't hard-code QEMU version

[Peter Maydell]

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 <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
---
 Makefile     |  2 +-
 docs/conf.py | 21 ++++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 46cb8e62571..526bac7f516 100644
--- a/Makefile
+++ b/Makefile
@@ -865,7 +865,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
 sphinxdocs: docs/devel/index.html docs/interop/index.html
 
 # Canned command to build a single manual
-build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
+build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
 # We assume all RST files in the manual's directory are used in it
 manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
 
diff --git a/docs/conf.py b/docs/conf.py
index 6a334f545ec..0842d44e930 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -75,11 +75,22 @@ author = u'The QEMU Project Developers'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
-# The short X.Y version.
-version = u'4.0'
-# The full version, including alpha/beta/rc tags.
-release = u'4.0'
+
+# Extract this information from the VERSION file, for the benefit of
+# standalone Sphinx runs as used by readthedocs.org. Builds run from
+# the Makefile will pass version and release on the sphinx-build
+# command line, which override this.
+try:
+    extracted_version = None
+    with open(os.path.join(qemu_docdir, '../VERSION')) as f:
+        extracted_version = f.readline().strip()
+except:
+    pass
+finally:
+    if extracted_version:
+        version = release = extracted_version
+    else:
+        version = release = "unknown version"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-- 
2.20.1

Re: [Qemu-devel] [PATCH v2 11/11] docs/conf.py: Don't hard-code QEMU version

[Philippe Mathieu-Daudé]

On 2/28/19 3:56 PM, Peter Maydell wrote:
> 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 <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>

> ---
>  Makefile     |  2 +-
>  docs/conf.py | 21 ++++++++++++++++-----
>  2 files changed, 17 insertions(+), 6 deletions(-)
> 
> diff --git a/Makefile b/Makefile
> index 46cb8e62571..526bac7f516 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -865,7 +865,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
>  sphinxdocs: docs/devel/index.html docs/interop/index.html
>  
>  # Canned command to build a single manual
> -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
>  # We assume all RST files in the manual's directory are used in it
>  manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
>  
> diff --git a/docs/conf.py b/docs/conf.py
> index 6a334f545ec..0842d44e930 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -75,11 +75,22 @@ author = u'The QEMU Project Developers'
>  # The version info for the project you're documenting, acts as replacement for
>  # |version| and |release|, also used in various other places throughout the
>  # built documents.
> -#
> -# The short X.Y version.
> -version = u'4.0'
> -# The full version, including alpha/beta/rc tags.
> -release = u'4.0'
> +
> +# Extract this information from the VERSION file, for the benefit of
> +# standalone Sphinx runs as used by readthedocs.org. Builds run from
> +# the Makefile will pass version and release on the sphinx-build
> +# command line, which override this.
> +try:
> +    extracted_version = None
> +    with open(os.path.join(qemu_docdir, '../VERSION')) as f:
> +        extracted_version = f.readline().strip()
> +except:
> +    pass
> +finally:
> +    if extracted_version:
> +        version = release = extracted_version
> +    else:
> +        version = release = "unknown version"
>  
>  # The language for content autogenerated by Sphinx. Refer to documentation
>  # for a list of supported languages.
> 

Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190228145624.24885-1-peter.maydell@linaro.org/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Message-id: 20190228145624.24885-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs
Type: series

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 * [new tag]               patchew/20190228145624.24885-1-peter.maydell@linaro.org -> patchew/20190228145624.24885-1-peter.maydell@linaro.org
Switched to a new branch 'test'
160e9b3050 docs/conf.py: Don't hard-code QEMU version
e6a8817ca2 Makefile: Abstract out "identify the pkgversion" code
dac902ad82 Makefile, configure: Support building rST documentation
58477e09dc docs: Provide separate conf.py for each manual we want
ec5a0d34bf docs/conf.py: Disable option warnings
4f84ff0c0f docs/conf.py: Don't include rST sources in HTML build
71184b1d76 docs/conf.py: Configure the 'alabaster' theme
092dffbc08 docs/conf.py: Disable unused _static directory
5f189c4d80 docs: Commit initial files from sphinx-quickstart
e50789da75 docs: Convert memory.txt to rst format
7aaa8d2896 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 7aaa8d2896b3 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit e50789da7586 (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#22: 
rename from docs/devel/memory.txt

total: 0 errors, 1 warnings, 195 lines checked

Patch 2/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
3/11 Checking commit 5f189c4d8024 (docs: Commit initial files from sphinx-quickstart)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#15: 
new file mode 100644

total: 0 errors, 1 warnings, 188 lines checked

Patch 3/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
4/11 Checking commit 092dffbc0833 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 71184b1d76ae (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit 4f84ff0c0f0a (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit ec5a0d34bf6c (docs/conf.py: Disable option warnings)
8/11 Checking commit 58477e09dc97 (docs: Provide separate conf.py for each manual we want)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#100: 
new file mode 100644

ERROR: line over 90 characters
#185: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

total: 1 errors, 1 warnings, 133 lines checked

Patch 8/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

9/11 Checking commit dac902ad82d8 (Makefile, configure: Support building rST documentation)
10/11 Checking commit e6a8817ca233 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 160e9b3050b5 (docs/conf.py: Don't hard-code QEMU version)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190228145624.24885-1-peter.maydell@linaro.org/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [http://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190228145624.24885-1-peter.maydell@linaro.org/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Message-id: 20190228145624.24885-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs
Type: series

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190228145624.24885-1-peter.maydell@linaro.org -> patchew/20190228145624.24885-1-peter.maydell@linaro.org
Switched to a new branch 'test'
024bddcb84 docs/conf.py: Don't hard-code QEMU version
c8cc9f6034 Makefile: Abstract out "identify the pkgversion" code
d58978ec2d Makefile, configure: Support building rST documentation
7fb0bc196a docs: Provide separate conf.py for each manual we want
7a70c6942e docs/conf.py: Disable option warnings
1eeee495fe docs/conf.py: Don't include rST sources in HTML build
2cc3efe707 docs/conf.py: Configure the 'alabaster' theme
0b2f8c0357 docs/conf.py: Disable unused _static directory
fd3d7e4d01 docs: Commit initial files from sphinx-quickstart
2fe1739868 docs: Convert memory.txt to rst format
e15af8618d docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit e15af8618d96 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 2fe1739868af (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#22: 
rename from docs/devel/memory.txt

total: 0 errors, 1 warnings, 195 lines checked

Patch 2/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
3/11 Checking commit fd3d7e4d01a8 (docs: Commit initial files from sphinx-quickstart)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#15: 
new file mode 100644

total: 0 errors, 1 warnings, 188 lines checked

Patch 3/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
4/11 Checking commit 0b2f8c03578f (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 2cc3efe70724 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit 1eeee495feaf (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 7a70c6942efd (docs/conf.py: Disable option warnings)
8/11 Checking commit 7fb0bc196a43 (docs: Provide separate conf.py for each manual we want)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#100: 
new file mode 100644

ERROR: line over 90 characters
#185: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

total: 1 errors, 1 warnings, 133 lines checked

Patch 8/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

9/11 Checking commit d58978ec2da8 (Makefile, configure: Support building rST documentation)
10/11 Checking commit c8cc9f60345a (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 024bddcb84a7 (docs/conf.py: Don't hard-code QEMU version)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190228145624.24885-1-peter.maydell@linaro.org/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [http://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[Aleksandar Markovic]

> Peter Maydell <peter.maydell@linaro.org> wrote:

> This patchset enables building and installing the various rST
> docs we have started to accumulate in our docs/ directory.

For the entire series:

Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>

It does this using Sphinx (which is the docs tooling that the
> Linux kernel uses). The series is not trying to take us in one
> giant leap to a brave new Sphinx-powered world -- it is simply
> setting up a framework so that we are at least building and
> shipping these documents and can gradually migrate other parts
> of our documentation to it.
>
> Changes v1->v2:
>  * Added a few missing Signed-off-by lines
>  * Provided a proper commit message for patch 8
>  * patch 9: only add 'sphinxdocs' target to 'all' if BUILD_DOCS
>    is defined (fixes building on systems without sphinx-build,
>    which will now just not build the docs rather than barfing)
>
> All patches except 9 have been reviewed.
>
> Feedback to v1 seemed to be positive, so I propose that (assuming
> no further issues found in code review) we commit this series
> before softfreeze for the 4.1 release.
>
>
> All the text below here is from the v1 cover letter, for context.
>
>
> The approach I've used here is that we will have multiple "manuals",
> as proposed by Paolo here:
>   https://wiki.qemu.org/Features/Documentation
> For the moment I've only created 'interop' and 'devel' as we don't
> yet have any rST files for 'user', 'system' or 'specs'.
>
> One slightly awkward mismatch between how Sphinx naturally wants
> to work and our requirements is that when Sphinx generates a
> documentation set all in one go it creates hyperlinks between
> all the docs, they all appear in a single top level table of
> contents, and so on. But for QEMU's docs we don't want to
> ship the "devel" manual to end-users. I've taken an approach
> suggested to me on sphinx-users
> (https://www.mail-archive.com/sphinx-users@googlegroups.com/msg03224.html)
> where we run Sphinx once per manual, and treat them as
> entirely separate documents. The config/tooling in this patchset
> also supports building everything in a single run, for compatibility
> with third-party docs sites like readthedocs.org.
>
> To see the results:
>
> What you get in the docs/ subdir of your build directory
> when you do a local build:
>  http://people.linaro.org/~peter.maydell/build-dir-docs/
> (follow the links to 'devel' and 'interop' for the two manuals)
>
> What we'll ship in 'make install' in /usr/local/share/doc/qemu/
> http://people.linaro.org/~peter.maydell/installed-docs/
> (should be same as the build dir except we don't ship 'devel')
>
> What you get with a standalone single-run docs build:
>  http://people.linaro.org/~peter.maydell/standalone-docs/index.html
>
> These use the default 'alabaster' theme from Sphinx. I
> also experimented with the 'read_the_docs' theme, which I
> do think looks nicer. Unfortunately it also requires the
> docs we install to include about 3MB of TrueType font files
> per manual, which is awkward licensing-wise as the TTFs are
> under the Open Font License and it's not completely clear to
> me that it's OK to ship those to use with a doc file that is
> GPLed. Alabaster doesn't ship fonts, which sidesteps both
> those problems.
>
> Other notes:
>  * this does not build the two .rst files that are directly
>    in docs/ (cpu-hotplug.rst and pr-manager.rst) -- we should
>    move these to whichever of the five manuals is the best place
>  * I do have some prototype patches which integrate the kernel's
>    kerneldoc Sphinx extension to parse doc comments in source
>    code. I haven't included them here because I think the 'devel'
>    manual is the lowest priority of the five. They might be
>    useful if we want to try things like building documentation
>    of supported machine models from in-code comments/etc, though.
>  * as noted in a previous email thread, the configure changes
>    now mean that building docs depends on build-sphinx being
>    available, so this is a new build-dep for --enable-docs.
>
>
> thanks
> -- PMM
>
>
> Peter Maydell (11):
>   docs/cpu-hotplug.rst: Fix rST markup issues
>   docs: Convert memory.txt to rst format
>   docs: Commit initial files from sphinx-quickstart
>   docs/conf.py: Disable unused _static directory
>   docs/conf.py: Configure the 'alabaster' theme
>   docs/conf.py: Don't include rST sources in HTML build
>   docs/conf.py: Disable option warnings
>   docs: Provide separate conf.py for each manual we want
>   Makefile, configure: Support building rST documentation
>   Makefile: Abstract out "identify the pkgversion" code
>   docs/conf.py: Don't hard-code QEMU version
>
>  configure                             |   4 +-
>  Makefile                              |  78 +++++++---
>  docs/conf.py                          | 215 ++++++++++++++++++++++++++
>  docs/cpu-hotplug.rst                  |   2 +-
>  docs/devel/conf.py                    |  15 ++
>  docs/devel/index.rst                  |  21 +++
>  docs/devel/{memory.txt => memory.rst} | 128 ++++++++-------
>  docs/index.rst                        |  15 ++
>  docs/interop/conf.py                  |  15 ++
>  docs/interop/index.rst                |  18 +++
>  10 files changed, 430 insertions(+), 81 deletions(-)
>  create mode 100644 docs/conf.py
>  create mode 100644 docs/devel/conf.py
>  create mode 100644 docs/devel/index.rst
>  rename docs/devel/{memory.txt => memory.rst} (85%)
>  create mode 100644 docs/index.rst
>  create mode 100644 docs/interop/conf.py
>  create mode 100644 docs/interop/index.rst
>
> --
> 2.20.1
>
>
>

Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190228145624.24885-1-peter.maydell@linaro.org/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Message-id: 20190228145624.24885-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs
Type: series

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190228145624.24885-1-peter.maydell@linaro.org -> patchew/20190228145624.24885-1-peter.maydell@linaro.org
Switched to a new branch 'test'
a49d6aa81e docs/conf.py: Don't hard-code QEMU version
bf28ac7e6d Makefile: Abstract out "identify the pkgversion" code
c0a06a1742 Makefile, configure: Support building rST documentation
a3160ea058 docs: Provide separate conf.py for each manual we want
ccb6fe82ea docs/conf.py: Disable option warnings
b9037d07de docs/conf.py: Don't include rST sources in HTML build
8123dad83f docs/conf.py: Configure the 'alabaster' theme
098bf5e0f0 docs/conf.py: Disable unused _static directory
4e11f73bf3 docs: Commit initial files from sphinx-quickstart
222469ce24 docs: Convert memory.txt to rst format
82f6c91892 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 82f6c91892d5 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 222469ce24e6 (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#23: 
rename from docs/devel/memory.txt

total: 0 errors, 1 warnings, 195 lines checked

Patch 2/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
3/11 Checking commit 4e11f73bf3a4 (docs: Commit initial files from sphinx-quickstart)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#16: 
new file mode 100644

total: 0 errors, 1 warnings, 188 lines checked

Patch 3/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
4/11 Checking commit 098bf5e0f04c (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 8123dad83ffe (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit b9037d07de4f (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit ccb6fe82ea95 (docs/conf.py: Disable option warnings)
8/11 Checking commit a3160ea05829 (docs: Provide separate conf.py for each manual we want)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#101: 
new file mode 100644

ERROR: line over 90 characters
#186: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

total: 1 errors, 1 warnings, 133 lines checked

Patch 8/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

9/11 Checking commit c0a06a17421c (Makefile, configure: Support building rST documentation)
10/11 Checking commit bf28ac7e6d4b (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit a49d6aa81e39 (docs/conf.py: Don't hard-code QEMU version)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190228145624.24885-1-peter.maydell@linaro.org/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [http://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190228145624.24885-1-peter.maydell@linaro.org/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Message-id: 20190228145624.24885-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs
Type: series

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190228145624.24885-1-peter.maydell@linaro.org -> patchew/20190228145624.24885-1-peter.maydell@linaro.org
Switched to a new branch 'test'
263d5bcd2e docs/conf.py: Don't hard-code QEMU version
5ca8826d2c Makefile: Abstract out "identify the pkgversion" code
dab7bd74a0 Makefile, configure: Support building rST documentation
ded03f3e49 docs: Provide separate conf.py for each manual we want
6e9e92cd26 docs/conf.py: Disable option warnings
d38917cf03 docs/conf.py: Don't include rST sources in HTML build
a69bfae417 docs/conf.py: Configure the 'alabaster' theme
a063dad0aa docs/conf.py: Disable unused _static directory
b6d15474a5 docs: Commit initial files from sphinx-quickstart
5ad9038bd0 docs: Convert memory.txt to rst format
f194b04fad docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit f194b04fad28 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 5ad9038bd0bf (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#23: 
rename from docs/devel/memory.txt

total: 0 errors, 1 warnings, 195 lines checked

Patch 2/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
3/11 Checking commit b6d15474a5b5 (docs: Commit initial files from sphinx-quickstart)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#16: 
new file mode 100644

total: 0 errors, 1 warnings, 188 lines checked

Patch 3/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
4/11 Checking commit a063dad0aabe (docs/conf.py: Disable unused _static directory)
5/11 Checking commit a69bfae41720 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit d38917cf030e (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 6e9e92cd2626 (docs/conf.py: Disable option warnings)
8/11 Checking commit ded03f3e49b0 (docs: Provide separate conf.py for each manual we want)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#101: 
new file mode 100644

ERROR: line over 90 characters
#186: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

total: 1 errors, 1 warnings, 133 lines checked

Patch 8/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

9/11 Checking commit dab7bd74a014 (Makefile, configure: Support building rST documentation)
10/11 Checking commit 5ca8826d2c38 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 263d5bcd2e77 (docs/conf.py: Don't hard-code QEMU version)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190228145624.24885-1-peter.maydell@linaro.org/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [http://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190228145624.24885-1-peter.maydell@linaro.org/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Message-id: 20190228145624.24885-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs
Type: series

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
   093a2af7b6..711d13d5e2  master     -> master
 t [tag update]            patchew/20190228145624.24885-1-peter.maydell@linaro.org -> patchew/20190228145624.24885-1-peter.maydell@linaro.org
Switched to a new branch 'test'
53b94aff2f docs/conf.py: Don't hard-code QEMU version
330898d126 Makefile: Abstract out "identify the pkgversion" code
746ded6058 Makefile, configure: Support building rST documentation
af4ddac57a docs: Provide separate conf.py for each manual we want
1e26a65048 docs/conf.py: Disable option warnings
7ab0842ba4 docs/conf.py: Don't include rST sources in HTML build
b4e4aeda31 docs/conf.py: Configure the 'alabaster' theme
e2e3d14d80 docs/conf.py: Disable unused _static directory
3da54d22e0 docs: Commit initial files from sphinx-quickstart
f57be7d1eb docs: Convert memory.txt to rst format
9c3839add1 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 9c3839add122 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit f57be7d1eb50 (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#23: 
rename from docs/devel/memory.txt

total: 0 errors, 1 warnings, 195 lines checked

Patch 2/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
3/11 Checking commit 3da54d22e07d (docs: Commit initial files from sphinx-quickstart)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#16: 
new file mode 100644

total: 0 errors, 1 warnings, 188 lines checked

Patch 3/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
4/11 Checking commit e2e3d14d8082 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit b4e4aeda317d (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit 7ab0842ba41e (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 1e26a650488d (docs/conf.py: Disable option warnings)
8/11 Checking commit af4ddac57a6f (docs: Provide separate conf.py for each manual we want)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#101: 
new file mode 100644

ERROR: line over 90 characters
#186: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

total: 1 errors, 1 warnings, 133 lines checked

Patch 8/11 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

9/11 Checking commit 746ded60586b (Makefile, configure: Support building rST documentation)
10/11 Checking commit 330898d126f6 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 53b94aff2f52 (docs/conf.py: Don't hard-code QEMU version)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190228145624.24885-1-peter.maydell@linaro.org/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [http://patchew.org/].
Please send your feedback to patchew-devel@redhat.com