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

[Qemu-devel] [PATCH 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.

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

[Qemu-devel] [PATCH 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>
---
 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 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
---
 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

[Qemu-devel] [PATCH 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>
---
 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 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>
---
 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 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>
---
 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 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>
---
 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 08/11] Separate conf.py for each manual we want

[Peter Maydell]

---
 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 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 b18281c61f3..9cd5c0cd0bd 100755
--- a/configure
+++ b/configure
@@ -4561,11 +4561,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 1278a3eb529..d519fadee39 100644
--- a/Makefile
+++ b/Makefile
@@ -387,7 +387,7 @@ dummy := $(call unnest-vars,, \
 
 include $(SRC_PATH)/tests/Makefile.include
 
-all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
+all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
 
 qemu-version.h: FORCE
 	$(call quiet-command, \
@@ -631,6 +631,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 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
@@ -651,6 +659,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
@@ -684,7 +695,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)"
@@ -835,6 +857,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","$@")
 
@@ -863,7 +902,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

[Qemu-devel] [PATCH 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>
---
 Makefile | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/Makefile b/Makefile
index d519fadee39..2d19d28a271 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
 
 #see Makefile.objs for the definition of QAPI_MODULES
@@ -391,23 +405,8 @@ all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
 
 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 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>
---
 Makefile     |  2 +-
 docs/conf.py | 21 ++++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 2d19d28a271..e342242d268 100644
--- a/Makefile
+++ b/Makefile
@@ -863,7 +863,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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
fdcde82e94 docs/conf.py: Don't hard-code QEMU version
95ff495343 Makefile: Abstract out "identify the pkgversion" code
ea4e36f66f Makefile, configure: Support building rST documentation
20761006f1 Separate conf.py for each manual we want
ab8cacd266 docs/conf.py: Disable option warnings
a58591c443 docs/conf.py: Don't include rST sources in HTML build
a5e1fff319 docs/conf.py: Configure the 'alabaster' theme
b9917d0a1b docs/conf.py: Disable unused _static directory
fd769099b3 docs: Commit initial files from sphinx-quickstart
9888afe4ce docs: Convert memory.txt to rst format
7c59983957 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 7c59983957ec (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 9888afe4cedd (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#21: 
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 fd769099b38b (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 b9917d0a1bce (docs/conf.py: Disable unused _static directory)
5/11 Checking commit a5e1fff319a6 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit a58591c44317 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit ab8cacd26625 (docs/conf.py: Disable option warnings)
8/11 Checking commit 20761006f1ff (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 ea4e36f66f9b (Makefile, configure: Support building rST documentation)
10/11 Checking commit 95ff495343ba (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit fdcde82e9438 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Submodule 'capstone' (https://git.qemu.org/git/capstone.git) registered for path 'capstone'
Submodule 'dtc' (https://git.qemu.org/git/dtc.git) registered for path 'dtc'
Submodule 'roms/QemuMacDrivers' (https://git.qemu.org/git/QemuMacDrivers.git) registered for path 'roms/QemuMacDrivers'
Submodule 'roms/SLOF' (https://git.qemu.org/git/SLOF.git) registered for path 'roms/SLOF'
Submodule 'roms/ipxe' (https://git.qemu.org/git/ipxe.git) registered for path 'roms/ipxe'
Submodule 'roms/openbios' (https://git.qemu.org/git/openbios.git) registered for path 'roms/openbios'
Submodule 'roms/openhackware' (https://git.qemu.org/git/openhackware.git) registered for path 'roms/openhackware'
Submodule 'roms/qemu-palcode' (https://git.qemu.org/git/qemu-palcode.git) registered for path 'roms/qemu-palcode'
Submodule 'roms/seabios' (https://git.qemu.org/git/seabios.git/) registered for path 'roms/seabios'
Submodule 'roms/seabios-hppa' (https://github.com/hdeller/seabios-hppa.git) registered for path 'roms/seabios-hppa'
Submodule 'roms/sgabios' (https://git.qemu.org/git/sgabios.git) registered for path 'roms/sgabios'
Submodule 'roms/skiboot' (https://git.qemu.org/git/skiboot.git) registered for path 'roms/skiboot'
Submodule 'roms/u-boot' (https://git.qemu.org/git/u-boot.git) registered for path 'roms/u-boot'
Submodule 'roms/u-boot-sam460ex' (https://git.qemu.org/git/u-boot-sam460ex.git) registered for path 'roms/u-boot-sam460ex'
Submodule 'tests/fp/berkeley-softfloat-3' (https://github.com/cota/berkeley-softfloat-3) registered for path 'tests/fp/berkeley-softfloat-3'
Submodule 'tests/fp/berkeley-testfloat-3' (https://github.com/cota/berkeley-testfloat-3) registered for path 'tests/fp/berkeley-testfloat-3'
Submodule 'ui/keycodemapdb' (https://git.qemu.org/git/keycodemapdb.git) registered for path 'ui/keycodemapdb'
Cloning into 'capstone'...
Submodule path 'capstone': checked out '22ead3e0bfdb87516656453336160e0a37b066bf'
Cloning into 'dtc'...
Submodule path 'dtc': checked out '88f18909db731a627456f26d779445f84e449536'
Cloning into 'roms/QemuMacDrivers'...
Submodule path 'roms/QemuMacDrivers': checked out 'd4e7d7ac663fcb55f1b93575445fcbca372f17a7'
Cloning into 'roms/SLOF'...
Submodule path 'roms/SLOF': checked out '9b7ab2fa020341dee8bf9df6c9cf40003e0136df'
Cloning into 'roms/ipxe'...
Submodule path 'roms/ipxe': checked out 'de4565cbe76ea9f7913a01f331be3ee901bb6e17'
Cloning into 'roms/openbios'...
Submodule path 'roms/openbios': checked out '441a84d3a642a10b948369c63f32367e8ff6395b'
Cloning into 'roms/openhackware'...
Submodule path 'roms/openhackware': checked out 'c559da7c8eec5e45ef1f67978827af6f0b9546f5'
Cloning into 'roms/qemu-palcode'...
Submodule path 'roms/qemu-palcode': checked out '51c237d7e20d05100eacadee2f61abc17e6bc097'
Cloning into 'roms/seabios'...
Submodule path 'roms/seabios': checked out 'a698c8995ffb2838296ec284fe3c4ad33dfca307'
Cloning into 'roms/seabios-hppa'...
Submodule path 'roms/seabios-hppa': checked out '1ef99a01572c2581c30e16e6fe69e9ea2ef92ce0'
Cloning into 'roms/sgabios'...
Submodule path 'roms/sgabios': checked out 'cbaee52287e5f32373181cff50a00b6c4ac9015a'
Cloning into 'roms/skiboot'...
Submodule path 'roms/skiboot': checked out 'e0ee24c27a172bcf482f6f2bc905e6211c134bcc'
Cloning into 'roms/u-boot'...
Submodule path 'roms/u-boot': checked out 'd85ca029f257b53a96da6c2fb421e78a003a9943'
Cloning into 'roms/u-boot-sam460ex'...
Submodule path 'roms/u-boot-sam460ex': checked out '60b3916f33e617a815973c5a6df77055b2e3a588'
Cloning into 'tests/fp/berkeley-softfloat-3'...
Submodule path 'tests/fp/berkeley-softfloat-3': checked out 'b64af41c3276f97f0e181920400ee056b9c88037'
Cloning into 'tests/fp/berkeley-testfloat-3'...
Submodule path 'tests/fp/berkeley-testfloat-3': checked out '5a59dcec19327396a011a17fd924aed4fec416b3'
Cloning into 'ui/keycodemapdb'...
Submodule path 'ui/keycodemapdb': checked out '6b3d716e2b6472eb7189d3220552280ef3d832ce'
Switched to a new branch 'test'
fdcde82 docs/conf.py: Don't hard-code QEMU version
95ff495 Makefile: Abstract out "identify the pkgversion" code
ea4e36f Makefile, configure: Support building rST documentation
2076100 Separate conf.py for each manual we want
ab8cacd docs/conf.py: Disable option warnings
a58591c docs/conf.py: Don't include rST sources in HTML build
a5e1fff docs/conf.py: Configure the 'alabaster' theme
b9917d0 docs/conf.py: Disable unused _static directory
fd76909 docs: Commit initial files from sphinx-quickstart
9888afe docs: Convert memory.txt to rst format
7c59983 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 7c59983957ec (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 9888afe4cedd (docs: Convert memory.txt to rst format)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#21: 
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 fd769099b38b (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 b9917d0a1bce (docs/conf.py: Disable unused _static directory)
5/11 Checking commit a5e1fff319a6 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit a58591c44317 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit ab8cacd26625 (docs/conf.py: Disable option warnings)
8/11 Checking commit 20761006f1ff (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 ea4e36f66f9b (Makefile, configure: Support building rST documentation)
10/11 Checking commit 95ff495343ba (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit fdcde82e9438 (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/20190201145035.22739-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 09/11] Makefile, configure: Support building rST documentation

[Alex Bennée]

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

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

Hmm we manage to break Travis CI:

  https://travis-ci.org/stsquad/qemu/jobs/487512292#L902

It reports:

  Documentation     no

But then proceeds to barf:

  https://travis-ci.org/stsquad/qemu/jobs/487512292#L1395

with:

  /bin/sh: 1: sphinx-build: not found
  Makefile:871: recipe for target 'docs/devel/index.html' failed
  make: *** [docs/devel/index.html] Error 127

>
> 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 b18281c61f3..9cd5c0cd0bd 100755
> --- a/configure
> +++ b/configure
> @@ -4561,11 +4561,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 1278a3eb529..d519fadee39 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -387,7 +387,7 @@ dummy := $(call unnest-vars,, \
>
>  include $(SRC_PATH)/tests/Makefile.include
>
> -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
> +all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
>
>  qemu-version.h: FORCE
>  	$(call quiet-command, \
> @@ -631,6 +631,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 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
> @@ -651,6 +659,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
> @@ -684,7 +695,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)"
> @@ -835,6 +857,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","$@")
>
> @@ -863,7 +902,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


--
Alex Bennée

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

[Peter Maydell]

On Fri, 1 Feb 2019 at 16:19, Alex Bennée <alex.bennee@linaro.org> wrote:
> It reports:
>
>   Documentation     no
>
> But then proceeds to barf:
>
>   https://travis-ci.org/stsquad/qemu/jobs/487512292#L1395
>
> with:
>
>   /bin/sh: 1: sphinx-build: not found
>   Makefile:871: recipe for target 'docs/devel/index.html' failed
>   make: *** [docs/devel/index.html] Error 127

Oops, yes. We shouldn't be adding the sphinxdocs target to
the all: list (or the sphinxdocs-install target to install:)
unless BUILD_DOCS is defined.

(Assuming we take this we should probably also add sphinx
to the set of deps we install for Travis, but a no-sphinx
build shouldn't break.)

thanks
-- PMM

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

[Alex Bennée]

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

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


--
Alex Bennée

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

[Alex Bennée]

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

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


--
Alex Bennée

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

[Alex Bennée]

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

> Commit the initial Sphinx conf.py and skeleton index.rst as
> generated with sphinx-quickstart
> ---
>  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'

Hmm I bet we forget to update this date. Does it have to be the date the
text was last touched or could we just go from the last commit in the tree?

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

Surely these need to come from the build system the same way the
build-id does?

Otherwise:

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>


--
Alex Bennée

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

[Alex Bennée]

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

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


--
Alex Bennée

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

[Alex Bennée]

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

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

I'm not sure what the title means... is the theme a reference to a
layout? I thought themes were colours and other such visual frippery
rather than actual content layout. But what do I know as a mere code
monkey...

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

>
> Signed-off-by: Peter Maydell <peter.maydell@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',
>      ]
>  }


--
Alex Bennée

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

[Alex Bennée]

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

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


--
Alex Bennée

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

[Alex Bennée]

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

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


--
Alex Bennée

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

[Peter Maydell]

On Fri, 1 Feb 2019 at 16:41, Alex Bennée <alex.bennee@linaro.org> wrote:
>
>
> Peter Maydell <peter.maydell@linaro.org> writes:

> > +# General information about the project.
> > +project = u'QEMU'
> > +copyright = u'2019, The QEMU Project Developers'
>
> Hmm I bet we forget to update this date. Does it have to be the date the
> text was last touched or could we just go from the last commit in the tree?

Yeah, this isn't ideal, but the same applies to the
string in QEMU_COPYRIGHT in qemu-common.h (as you can tell
from the fact that still says 2018!). If we can fix that
to be generated from something else we can fish it out when
we do the docs build too.

> > +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'
>
> Surely these need to come from the build system the same way the
> build-id does?

Yes, see later patch in the series. The idea with the patchset
structure here was that this patch is basically just the
autogenerated stuff (sphinx-quickstart asks a few simple questions
like project name and author which fills these in), and then
the following patches customize that. That seemed to me like
it would be easier to review than if I just squashed everything
into a single patch.

thanks
-- PMM

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

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
   cfe6c54..a1bc3e7  master     -> master
 - [tag update]      patchew/20190201124543.5945-1-cohuck@redhat.com -> patchew/20190201124543.5945-1-cohuck@redhat.com
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
 * [new tag]         patchew/20190201160653.13829-1-peter.maydell@linaro.org -> patchew/20190201160653.13829-1-peter.maydell@linaro.org
Switched to a new branch 'test'
566e309 docs/conf.py: Don't hard-code QEMU version
09887df Makefile: Abstract out "identify the pkgversion" code
cfc53bc Makefile, configure: Support building rST documentation
8dd4464 Separate conf.py for each manual we want
a08fc31 docs/conf.py: Disable option warnings
2d22b98 docs/conf.py: Don't include rST sources in HTML build
0e0c1c2 docs/conf.py: Configure the 'alabaster' theme
fa1935b docs/conf.py: Disable unused _static directory
a384f83 docs: Commit initial files from sphinx-quickstart
9d2a8ce docs: Convert memory.txt to rst format
858573e docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 858573e43e10 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 9d2a8ce2ea3c (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 a384f83c875c (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 fa1935bfae6c (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 0e0c1c2bdb53 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit 2d22b981a12b (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit a08fc31392c9 (docs/conf.py: Disable option warnings)
8/11 Checking commit 8dd44649383f (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 cfc53bc5d2d1 (Makefile, configure: Support building rST documentation)
10/11 Checking commit 09887dfd22f9 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 566e309a211a (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/20190201145035.22739-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 08/11] Separate conf.py for each manual we want

[Alex Bennée]

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

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

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

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


--
Alex Bennée

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

[Alex Bennée]

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

> 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 d519fadee39..2d19d28a271 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
>
>  #see Makefile.objs for the definition of QAPI_MODULES
> @@ -391,23 +405,8 @@ all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
>
>  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 $@; \


--
Alex Bennée

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

[Alex Bennée]

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

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

Ahh the perils of not reading ahead ;-)

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 2d19d28a271..e342242d268 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -863,7 +863,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.


--
Alex Bennée

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

[Alex Bennée]

Alex Bennée <alex.bennee@linaro.org> writes:

> Peter Maydell <peter.maydell@linaro.org> writes:
>
>> 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.)
>
> Hmm we manage to break Travis CI:
>
>   https://travis-ci.org/stsquad/qemu/jobs/487512292#L902
>
> It reports:
>
>   Documentation     no
>
> But then proceeds to barf:
>
>   https://travis-ci.org/stsquad/qemu/jobs/487512292#L1395
>
> with:
>
>   /bin/sh: 1: sphinx-build: not found
>   Makefile:871: recipe for target 'docs/devel/index.html' failed
>   make: *** [docs/devel/index.html] Error 127

I did the following:

modified   Makefile
@@ -322,6 +322,7 @@ endif
 ifdef CONFIG_TRACE_SYSTEMTAP
 DOCS+=scripts/qemu-trace-stap.1
 endif
+DOCS+=sphinxdocs
 else
 DOCS=
 endif
@@ -401,7 +402,7 @@ dummy := $(call unnest-vars,, \

 include $(SRC_PATH)/tests/Makefile.include

-all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
+all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules

 qemu-version.h: FORCE
 	$(call quiet-command, \
@@ -699,13 +700,7 @@ for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_doc
 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-doc: $(DOCS)
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
@@ -737,6 +732,7 @@ ifdef CONFIG_VIRTFS
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DATA) fsdev/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
 endif
+	$(call install-manual,interop)

 install-datadir:
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_datadir)"

--
Alex Bennée

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

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
50a0f0d5ce docs/conf.py: Don't hard-code QEMU version
7b5fa8d953 Makefile: Abstract out "identify the pkgversion" code
e9566ecba8 Makefile, configure: Support building rST documentation
08de86173b Separate conf.py for each manual we want
42806c50e2 docs/conf.py: Disable option warnings
e50a106d7d docs/conf.py: Don't include rST sources in HTML build
2e1a65022b docs/conf.py: Configure the 'alabaster' theme
14b7b18b70 docs/conf.py: Disable unused _static directory
d991b4506b docs: Commit initial files from sphinx-quickstart
4f429cddf4 docs: Convert memory.txt to rst format
56f8e4a6c7 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 56f8e4a6c708 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 4f429cddf421 (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 d991b4506b86 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 14b7b18b70c3 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 2e1a65022bc1 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit e50a106d7dc5 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 42806c50e248 (docs/conf.py: Disable option warnings)
8/11 Checking commit 08de86173b2e (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 e9566ecba8ed (Makefile, configure: Support building rST documentation)
10/11 Checking commit 7b5fa8d95384 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 50a0f0d5ce2d (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
50a0f0d docs/conf.py: Don't hard-code QEMU version
7b5fa8d Makefile: Abstract out "identify the pkgversion" code
e9566ec Makefile, configure: Support building rST documentation
08de861 Separate conf.py for each manual we want
42806c5 docs/conf.py: Disable option warnings
e50a106 docs/conf.py: Don't include rST sources in HTML build
2e1a650 docs/conf.py: Configure the 'alabaster' theme
14b7b18 docs/conf.py: Disable unused _static directory
d991b45 docs: Commit initial files from sphinx-quickstart
4f429cd docs: Convert memory.txt to rst format
56f8e4a docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 56f8e4a6c708 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 4f429cddf421 (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 d991b4506b86 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 14b7b18b70c3 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 2e1a65022bc1 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit e50a106d7dc5 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 42806c50e248 (docs/conf.py: Disable option warnings)
8/11 Checking commit 08de86173b2e (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 e9566ecba8ed (Makefile, configure: Support building rST documentation)
10/11 Checking commit 7b5fa8d95384 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 50a0f0d5ce2d (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/20190201145035.22739-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 09/11] Makefile, configure: Support building rST documentation

[Peter Maydell]

On Fri, 1 Feb 2019 at 17:11, Alex Bennée <alex.bennee@linaro.org> wrote:
> I did the following:
>
> modified   Makefile
> @@ -322,6 +322,7 @@ endif
>  ifdef CONFIG_TRACE_SYSTEMTAP
>  DOCS+=scripts/qemu-trace-stap.1
>  endif
> +DOCS+=sphinxdocs
>  else
>  DOCS=
>  endif

This kind of works, but it's a bit odd, because DOCS is otherwise
a list of files and we assume it is in a couple of places. (For
instance we call "rm -f $(DOCS)" in the distclean target.)

thanks
-- PMM

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

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
22f2dcd906 docs/conf.py: Don't hard-code QEMU version
975039b71d Makefile: Abstract out "identify the pkgversion" code
eb6658e521 Makefile, configure: Support building rST documentation
dca673cf2e Separate conf.py for each manual we want
2e60fa614a docs/conf.py: Disable option warnings
ccb59ac3b5 docs/conf.py: Don't include rST sources in HTML build
cebfc8b424 docs/conf.py: Configure the 'alabaster' theme
619b69ea8e docs/conf.py: Disable unused _static directory
4ce6a5d59f docs: Commit initial files from sphinx-quickstart
0e08f4f139 docs: Convert memory.txt to rst format
2c6df0cfed docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 2c6df0cfed8f (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 0e08f4f13950 (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 4ce6a5d59f41 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 619b69ea8ee3 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit cebfc8b42425 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit ccb59ac3b537 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 2e60fa614a20 (docs/conf.py: Disable option warnings)
8/11 Checking commit dca673cf2ea3 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 eb6658e52120 (Makefile, configure: Support building rST documentation)
10/11 Checking commit 975039b71d40 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 22f2dcd90680 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Submodule 'capstone' (https://git.qemu.org/git/capstone.git) registered for path 'capstone'
Submodule 'dtc' (https://git.qemu.org/git/dtc.git) registered for path 'dtc'
Submodule 'roms/QemuMacDrivers' (https://git.qemu.org/git/QemuMacDrivers.git) registered for path 'roms/QemuMacDrivers'
Submodule 'roms/SLOF' (https://git.qemu.org/git/SLOF.git) registered for path 'roms/SLOF'
Submodule 'roms/ipxe' (https://git.qemu.org/git/ipxe.git) registered for path 'roms/ipxe'
Submodule 'roms/openbios' (https://git.qemu.org/git/openbios.git) registered for path 'roms/openbios'
Submodule 'roms/openhackware' (https://git.qemu.org/git/openhackware.git) registered for path 'roms/openhackware'
Submodule 'roms/qemu-palcode' (https://git.qemu.org/git/qemu-palcode.git) registered for path 'roms/qemu-palcode'
Submodule 'roms/seabios' (https://git.qemu.org/git/seabios.git/) registered for path 'roms/seabios'
Submodule 'roms/seabios-hppa' (https://github.com/hdeller/seabios-hppa.git) registered for path 'roms/seabios-hppa'
Submodule 'roms/sgabios' (https://git.qemu.org/git/sgabios.git) registered for path 'roms/sgabios'
Submodule 'roms/skiboot' (https://git.qemu.org/git/skiboot.git) registered for path 'roms/skiboot'
Submodule 'roms/u-boot' (https://git.qemu.org/git/u-boot.git) registered for path 'roms/u-boot'
Submodule 'roms/u-boot-sam460ex' (https://git.qemu.org/git/u-boot-sam460ex.git) registered for path 'roms/u-boot-sam460ex'
Submodule 'tests/fp/berkeley-softfloat-3' (https://github.com/cota/berkeley-softfloat-3) registered for path 'tests/fp/berkeley-softfloat-3'
Submodule 'tests/fp/berkeley-testfloat-3' (https://github.com/cota/berkeley-testfloat-3) registered for path 'tests/fp/berkeley-testfloat-3'
Submodule 'ui/keycodemapdb' (https://git.qemu.org/git/keycodemapdb.git) registered for path 'ui/keycodemapdb'
Cloning into 'capstone'...
Submodule path 'capstone': checked out '22ead3e0bfdb87516656453336160e0a37b066bf'
Cloning into 'dtc'...
Submodule path 'dtc': checked out '88f18909db731a627456f26d779445f84e449536'
Cloning into 'roms/QemuMacDrivers'...
Submodule path 'roms/QemuMacDrivers': checked out 'd4e7d7ac663fcb55f1b93575445fcbca372f17a7'
Cloning into 'roms/SLOF'...
Submodule path 'roms/SLOF': checked out '9b7ab2fa020341dee8bf9df6c9cf40003e0136df'
Cloning into 'roms/ipxe'...
Submodule path 'roms/ipxe': checked out 'de4565cbe76ea9f7913a01f331be3ee901bb6e17'
Cloning into 'roms/openbios'...
Submodule path 'roms/openbios': checked out '441a84d3a642a10b948369c63f32367e8ff6395b'
Cloning into 'roms/openhackware'...
Submodule path 'roms/openhackware': checked out 'c559da7c8eec5e45ef1f67978827af6f0b9546f5'
Cloning into 'roms/qemu-palcode'...
Submodule path 'roms/qemu-palcode': checked out '51c237d7e20d05100eacadee2f61abc17e6bc097'
Cloning into 'roms/seabios'...
Submodule path 'roms/seabios': checked out 'a698c8995ffb2838296ec284fe3c4ad33dfca307'
Cloning into 'roms/seabios-hppa'...
Submodule path 'roms/seabios-hppa': checked out '1ef99a01572c2581c30e16e6fe69e9ea2ef92ce0'
Cloning into 'roms/sgabios'...
Submodule path 'roms/sgabios': checked out 'cbaee52287e5f32373181cff50a00b6c4ac9015a'
Cloning into 'roms/skiboot'...
Submodule path 'roms/skiboot': checked out 'e0ee24c27a172bcf482f6f2bc905e6211c134bcc'
Cloning into 'roms/u-boot'...
Submodule path 'roms/u-boot': checked out 'd85ca029f257b53a96da6c2fb421e78a003a9943'
Cloning into 'roms/u-boot-sam460ex'...
Submodule path 'roms/u-boot-sam460ex': checked out '60b3916f33e617a815973c5a6df77055b2e3a588'
Cloning into 'tests/fp/berkeley-softfloat-3'...
Submodule path 'tests/fp/berkeley-softfloat-3': checked out 'b64af41c3276f97f0e181920400ee056b9c88037'
Cloning into 'tests/fp/berkeley-testfloat-3'...
Submodule path 'tests/fp/berkeley-testfloat-3': checked out '5a59dcec19327396a011a17fd924aed4fec416b3'
Cloning into 'ui/keycodemapdb'...
Submodule path 'ui/keycodemapdb': checked out '6b3d716e2b6472eb7189d3220552280ef3d832ce'
Switched to a new branch 'test'
50a0f0d docs/conf.py: Don't hard-code QEMU version
7b5fa8d Makefile: Abstract out "identify the pkgversion" code
e9566ec Makefile, configure: Support building rST documentation
08de861 Separate conf.py for each manual we want
42806c5 docs/conf.py: Disable option warnings
e50a106 docs/conf.py: Don't include rST sources in HTML build
2e1a650 docs/conf.py: Configure the 'alabaster' theme
14b7b18 docs/conf.py: Disable unused _static directory
d991b45 docs: Commit initial files from sphinx-quickstart
4f429cd docs: Convert memory.txt to rst format
56f8e4a docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 56f8e4a6c708 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 4f429cddf421 (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 d991b4506b86 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 14b7b18b70c3 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 2e1a65022bc1 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit e50a106d7dc5 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 42806c50e248 (docs/conf.py: Disable option warnings)
8/11 Checking commit 08de86173b2e (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 e9566ecba8ed (Makefile, configure: Support building rST documentation)
10/11 Checking commit 7b5fa8d95384 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 50a0f0d5ce2d (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
b01607c docs/conf.py: Don't hard-code QEMU version
d2709f5 Makefile: Abstract out "identify the pkgversion" code
495f73c Makefile, configure: Support building rST documentation
6e97894 Separate conf.py for each manual we want
e44ad7e docs/conf.py: Disable option warnings
fadd9f4 docs/conf.py: Don't include rST sources in HTML build
6e438de docs/conf.py: Configure the 'alabaster' theme
e208e08 docs/conf.py: Disable unused _static directory
abaf4de docs: Commit initial files from sphinx-quickstart
fba4ad9 docs: Convert memory.txt to rst format
eb6998f docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit eb6998fbf3b5 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit fba4ad903b15 (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 abaf4deb75a9 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 e208e0896ff1 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 6e438de47811 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit fadd9f417dc4 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit e44ad7e07445 (docs/conf.py: Disable option warnings)
8/11 Checking commit 6e97894f5831 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 495f73c795c2 (Makefile, configure: Support building rST documentation)
10/11 Checking commit d2709f595efd (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit b01607c6e1d9 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
Switched to a new branch 'test'
b696ee8efa docs/conf.py: Don't hard-code QEMU version
24606d9e76 Makefile: Abstract out "identify the pkgversion" code
ef460d14bb Makefile, configure: Support building rST documentation
eecbbbcc67 Separate conf.py for each manual we want
b6ddfd9964 docs/conf.py: Disable option warnings
b6174039e6 docs/conf.py: Don't include rST sources in HTML build
e8bff0e834 docs/conf.py: Configure the 'alabaster' theme
68de0536e9 docs/conf.py: Disable unused _static directory
93b5d1dbd8 docs: Commit initial files from sphinx-quickstart
73ad63cf3d docs: Convert memory.txt to rst format
cf0a8364f6 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit cf0a8364f6ea (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 73ad63cf3d96 (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 93b5d1dbd85f (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 68de0536e9c7 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit e8bff0e834ec (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit b6174039e688 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit b6ddfd9964ab (docs/conf.py: Disable option warnings)
8/11 Checking commit eecbbbcc6737 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 ef460d14bb09 (Makefile, configure: Support building rST documentation)
10/11 Checking commit 24606d9e76ca (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit b696ee8efa34 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
aed193d221 docs/conf.py: Don't hard-code QEMU version
40d4015362 Makefile: Abstract out "identify the pkgversion" code
728e072ddf Makefile, configure: Support building rST documentation
faf59c0dcd Separate conf.py for each manual we want
52b3db4b96 docs/conf.py: Disable option warnings
9f35db088a docs/conf.py: Don't include rST sources in HTML build
baf81fd590 docs/conf.py: Configure the 'alabaster' theme
1dc23cbf0f docs/conf.py: Disable unused _static directory
0adbe3fb61 docs: Commit initial files from sphinx-quickstart
6396cd9ed3 docs: Convert memory.txt to rst format
2aa8287d54 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 2aa8287d54ab (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 6396cd9ed34f (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 0adbe3fb6111 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 1dc23cbf0fc2 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit baf81fd590b5 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit 9f35db088a8f (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 52b3db4b9683 (docs/conf.py: Disable option warnings)
8/11 Checking commit faf59c0dcdfc (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#160: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 728e072ddf36 (Makefile, configure: Support building rST documentation)
10/11 Checking commit 40d401536240 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit aed193d22116 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
ea679f0a91 docs/conf.py: Don't hard-code QEMU version
9c6cbba2e1 Makefile: Abstract out "identify the pkgversion" code
526f97104a Makefile, configure: Support building rST documentation
665a9ff147 Separate conf.py for each manual we want
4a0ad1654a docs/conf.py: Disable option warnings
daffe99f6b docs/conf.py: Don't include rST sources in HTML build
7f2b1c3878 docs/conf.py: Configure the 'alabaster' theme
0edad2daa3 docs/conf.py: Disable unused _static directory
d698375a4c docs: Commit initial files from sphinx-quickstart
bca5202bdd docs: Convert memory.txt to rst format
0e9ffb13db docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 0e9ffb13dbaa (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit bca5202bddee (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 d698375a4c62 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 0edad2daa354 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 7f2b1c387830 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit daffe99f6be5 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 4a0ad1654af4 (docs/conf.py: Disable option warnings)
8/11 Checking commit 665a9ff14735 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#161: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 526f97104aac (Makefile, configure: Support building rST documentation)
10/11 Checking commit 9c6cbba2e17b (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit ea679f0a91a6 (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/20190201145035.22739-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 03/11] docs: Commit initial files from sphinx-quickstart

[Peter Maydell]

On Fri, 1 Feb 2019 at 14:50, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Commit the initial Sphinx conf.py and skeleton index.rst as
> generated with sphinx-quickstart

Oops, patchew points out that I forgot

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

thanks
-- PMM

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

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
ea679f0 docs/conf.py: Don't hard-code QEMU version
9c6cbba Makefile: Abstract out "identify the pkgversion" code
526f971 Makefile, configure: Support building rST documentation
665a9ff Separate conf.py for each manual we want
4a0ad16 docs/conf.py: Disable option warnings
daffe99 docs/conf.py: Don't include rST sources in HTML build
7f2b1c3 docs/conf.py: Configure the 'alabaster' theme
0edad2d docs/conf.py: Disable unused _static directory
d698375 docs: Commit initial files from sphinx-quickstart
bca5202 docs: Convert memory.txt to rst format
0e9ffb1 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 0e9ffb13dbaa (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit bca5202bddee (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 d698375a4c62 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 0edad2daa354 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 7f2b1c387830 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit daffe99f6be5 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 4a0ad1654af4 (docs/conf.py: Disable option warnings)
8/11 Checking commit 665a9ff14735 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#161: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 526f97104aac (Makefile, configure: Support building rST documentation)
10/11 Checking commit 9c6cbba2e17b (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit ea679f0a91a6 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Submodule 'capstone' (https://git.qemu.org/git/capstone.git) registered for path 'capstone'
Submodule 'dtc' (https://git.qemu.org/git/dtc.git) registered for path 'dtc'
Submodule 'roms/QemuMacDrivers' (https://git.qemu.org/git/QemuMacDrivers.git) registered for path 'roms/QemuMacDrivers'
Submodule 'roms/SLOF' (https://git.qemu.org/git/SLOF.git) registered for path 'roms/SLOF'
Submodule 'roms/ipxe' (https://git.qemu.org/git/ipxe.git) registered for path 'roms/ipxe'
Submodule 'roms/openbios' (https://git.qemu.org/git/openbios.git) registered for path 'roms/openbios'
Submodule 'roms/openhackware' (https://git.qemu.org/git/openhackware.git) registered for path 'roms/openhackware'
Submodule 'roms/qemu-palcode' (https://git.qemu.org/git/qemu-palcode.git) registered for path 'roms/qemu-palcode'
Submodule 'roms/seabios' (https://git.qemu.org/git/seabios.git/) registered for path 'roms/seabios'
Submodule 'roms/seabios-hppa' (https://github.com/hdeller/seabios-hppa.git) registered for path 'roms/seabios-hppa'
Submodule 'roms/sgabios' (https://git.qemu.org/git/sgabios.git) registered for path 'roms/sgabios'
Submodule 'roms/skiboot' (https://git.qemu.org/git/skiboot.git) registered for path 'roms/skiboot'
Submodule 'roms/u-boot' (https://git.qemu.org/git/u-boot.git) registered for path 'roms/u-boot'
Submodule 'roms/u-boot-sam460ex' (https://git.qemu.org/git/u-boot-sam460ex.git) registered for path 'roms/u-boot-sam460ex'
Submodule 'tests/fp/berkeley-softfloat-3' (https://github.com/cota/berkeley-softfloat-3) registered for path 'tests/fp/berkeley-softfloat-3'
Submodule 'tests/fp/berkeley-testfloat-3' (https://github.com/cota/berkeley-testfloat-3) registered for path 'tests/fp/berkeley-testfloat-3'
Submodule 'ui/keycodemapdb' (https://git.qemu.org/git/keycodemapdb.git) registered for path 'ui/keycodemapdb'
Cloning into 'capstone'...
Submodule path 'capstone': checked out '22ead3e0bfdb87516656453336160e0a37b066bf'
Cloning into 'dtc'...
Submodule path 'dtc': checked out '88f18909db731a627456f26d779445f84e449536'
Cloning into 'roms/QemuMacDrivers'...
Submodule path 'roms/QemuMacDrivers': checked out 'd4e7d7ac663fcb55f1b93575445fcbca372f17a7'
Cloning into 'roms/SLOF'...
Submodule path 'roms/SLOF': checked out '9b7ab2fa020341dee8bf9df6c9cf40003e0136df'
Cloning into 'roms/ipxe'...
Submodule path 'roms/ipxe': checked out 'de4565cbe76ea9f7913a01f331be3ee901bb6e17'
Cloning into 'roms/openbios'...
Submodule path 'roms/openbios': checked out '441a84d3a642a10b948369c63f32367e8ff6395b'
Cloning into 'roms/openhackware'...
Submodule path 'roms/openhackware': checked out 'c559da7c8eec5e45ef1f67978827af6f0b9546f5'
Cloning into 'roms/qemu-palcode'...
Submodule path 'roms/qemu-palcode': checked out '51c237d7e20d05100eacadee2f61abc17e6bc097'
Cloning into 'roms/seabios'...
Submodule path 'roms/seabios': checked out 'a698c8995ffb2838296ec284fe3c4ad33dfca307'
Cloning into 'roms/seabios-hppa'...
Submodule path 'roms/seabios-hppa': checked out '1ef99a01572c2581c30e16e6fe69e9ea2ef92ce0'
Cloning into 'roms/sgabios'...
Submodule path 'roms/sgabios': checked out 'cbaee52287e5f32373181cff50a00b6c4ac9015a'
Cloning into 'roms/skiboot'...
Submodule path 'roms/skiboot': checked out 'e0ee24c27a172bcf482f6f2bc905e6211c134bcc'
Cloning into 'roms/u-boot'...
Submodule path 'roms/u-boot': checked out 'd85ca029f257b53a96da6c2fb421e78a003a9943'
Cloning into 'roms/u-boot-sam460ex'...
Submodule path 'roms/u-boot-sam460ex': checked out '60b3916f33e617a815973c5a6df77055b2e3a588'
Cloning into 'tests/fp/berkeley-softfloat-3'...
Submodule path 'tests/fp/berkeley-softfloat-3': checked out 'b64af41c3276f97f0e181920400ee056b9c88037'
Cloning into 'tests/fp/berkeley-testfloat-3'...
Submodule path 'tests/fp/berkeley-testfloat-3': checked out '5a59dcec19327396a011a17fd924aed4fec416b3'
Cloning into 'ui/keycodemapdb'...
Submodule path 'ui/keycodemapdb': checked out '6b3d716e2b6472eb7189d3220552280ef3d832ce'
Switched to a new branch 'test'
ea679f0 docs/conf.py: Don't hard-code QEMU version
9c6cbba Makefile: Abstract out "identify the pkgversion" code
526f971 Makefile, configure: Support building rST documentation
665a9ff Separate conf.py for each manual we want
4a0ad16 docs/conf.py: Disable option warnings
daffe99 docs/conf.py: Don't include rST sources in HTML build
7f2b1c3 docs/conf.py: Configure the 'alabaster' theme
0edad2d docs/conf.py: Disable unused _static directory
d698375 docs: Commit initial files from sphinx-quickstart
bca5202 docs: Convert memory.txt to rst format
0e9ffb1 docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit 0e9ffb13dbaa (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit bca5202bddee (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 d698375a4c62 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 0edad2daa354 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 7f2b1c387830 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit daffe99f6be5 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 4a0ad1654af4 (docs/conf.py: Disable option warnings)
8/11 Checking commit 665a9ff14735 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#161: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 526f97104aac (Makefile, configure: Support building rST documentation)
10/11 Checking commit 9c6cbba2e17b (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit ea679f0a91a6 (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[Peter Maydell]

On Fri, 1 Feb 2019 at 15:06, <no-reply@patchew.org> wrote:
>
> Patchew URL: https://patchew.org/QEMU/20190201145035.22739-1-peter.maydell@linaro.org/
>
>
>
> Hi,
>
> This series seems to have some coding style problems. See output below for
> more information:
>
> Subject: [Qemu-devel] [PATCH 00/11] Enable build and install of our rST docs
> Type: series
> Message-id: 20190201145035.22739-1-peter.maydell@linaro.org

Hi Fam -- do you know why Patchew has sent a dozen emails for the
checkpatch issues in this patch series? It seems a bit excessive
when one would suffice...

thanks
-- PMM

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

[no-reply]

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



Hi,

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

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

=== TEST SCRIPT BEGIN ===
#!/bin/bash
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
 - [tag update]      patchew/20190201145035.22739-1-peter.maydell@linaro.org -> patchew/20190201145035.22739-1-peter.maydell@linaro.org
Switched to a new branch 'test'
429e245 docs/conf.py: Don't hard-code QEMU version
d1d73e3 Makefile: Abstract out "identify the pkgversion" code
999c09b Makefile, configure: Support building rST documentation
34bd2da Separate conf.py for each manual we want
9a6c5a4 docs/conf.py: Disable option warnings
c466233 docs/conf.py: Don't include rST sources in HTML build
0af2097 docs/conf.py: Configure the 'alabaster' theme
dd1b449 docs/conf.py: Disable unused _static directory
76f4d9d docs: Commit initial files from sphinx-quickstart
191561b docs: Convert memory.txt to rst format
f72de6c docs/cpu-hotplug.rst: Fix rST markup issues

=== OUTPUT BEGIN ===
1/11 Checking commit f72de6c70ee6 (docs/cpu-hotplug.rst: Fix rST markup issues)
2/11 Checking commit 191561bcbdc6 (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 76f4d9d42833 (docs: Commit initial files from sphinx-quickstart)
ERROR: Missing Signed-off-by: line(s)

total: 1 errors, 0 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 dd1b44918905 (docs/conf.py: Disable unused _static directory)
5/11 Checking commit 0af20971b269 (docs/conf.py: Configure the 'alabaster' theme)
6/11 Checking commit c46623391238 (docs/conf.py: Don't include rST sources in HTML build)
7/11 Checking commit 9a6c5a4a34fd (docs/conf.py: Disable option warnings)
8/11 Checking commit 34bd2dab5fb9 (Separate conf.py for each manual we want)
ERROR: line over 90 characters
#161: FILE: docs/interop/conf.py:15:
+html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'

ERROR: Missing Signed-off-by: line(s)

total: 2 errors, 0 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 999c09b2bb2b (Makefile, configure: Support building rST documentation)
10/11 Checking commit d1d73e341bf5 (Makefile: Abstract out "identify the pkgversion" code)
11/11 Checking commit 429e245a7c5f (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/20190201145035.22739-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 00/11] Enable build and install of our rST docs

[no-reply]

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



Hi,

This series failed the docker-mingw@fedora build test. Please find the testing commands and
their output below. If you have Docker installed, you can probably reproduce it
locally.

=== TEST SCRIPT BEGIN ===
#!/bin/bash
time make docker-test-mingw@fedora SHOW_ENV=1 J=14
=== TEST SCRIPT END ===


Configure options:
--enable-werror --target-list=x86_64-softmmu,aarch64-softmmu --prefix=/tmp/qemu-test/install --python=/usr/bin/python3 --cross-prefix=x86_64-w64-mingw32- --enable-trace-backends=simple --enable-gnutls --enable-nettle --enable-curl --enable-vnc --enable-bzip2 --enable-guest-agent --with-sdlabi=2.0
ERROR: unknown option --with-sdlabi=2.0
Try '/tmp/qemu-test/src/configure --help' for more information
# QEMU configure log Sun Feb  3 15:14:45 UTC 2019
# Configured with: '/tmp/qemu-test/src/configure' '--enable-werror' '--target-list=x86_64-softmmu,aarch64-softmmu' '--prefix=/tmp/qemu-test/install' '--python=/usr/bin/python3' '--cross-prefix=x86_64-w64-mingw32-' '--enable-trace-backends=simple' '--enable-gnutls' '--enable-nettle' '--enable-curl' '--enable-vnc' '--enable-bzip2' '--enable-guest-agent' '--with-sdlabi=2.0'
---
funcs: do_compiler do_cc compile_object check_define main
lines: 92 122 617 634 0
x86_64-w64-mingw32-gcc -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wall -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -c -o config-temp/qemu-conf.o config-temp/qemu-conf.c
config-temp/qemu-conf.c:2:2: error: #error __linux__ not defined
 #error __linux__ not defined
  ^~~~~

---
funcs: do_compiler do_cc compile_object check_define main
lines: 92 122 617 686 0
x86_64-w64-mingw32-gcc -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wall -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -c -o config-temp/qemu-conf.o config-temp/qemu-conf.c
config-temp/qemu-conf.c:2:2: error: #error __i386__ not defined
 #error __i386__ not defined
  ^~~~~

---
funcs: do_compiler do_cc compile_object check_define main
lines: 92 122 617 689 0
x86_64-w64-mingw32-gcc -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wall -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -c -o config-temp/qemu-conf.o config-temp/qemu-conf.c
config-temp/qemu-conf.c:2:2: error: #error __ILP32__ not defined
 #error __ILP32__ not defined
  ^~~~~

---
lines: 92 128 920 0
x86_64-w64-mingw32-gcc -mthreads -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wall -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -o config-temp/qemu-conf.exe config-temp/qemu-conf.c -g -liberty
/usr/lib/gcc/x86_64-w64-mingw32/8.2.0/../../../../x86_64-w64-mingw32/bin/ld: cannot find -liberty
collect2: error: ld returned 1 exit status
Failed to run 'configure'
Traceback (most recent call last):
  File "./tests/docker/docker.py", line 563, in <module>


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

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

[Peter Maydell]

Ping! Thanks to Alex for doing low-level review of this patchset.
I'm particularly interested in high-level review:
 * is this the right way to be going?
 * if we committed this and then did a release with the
   docs as they are like this, would that be ok?
 * what's the most important next step after this?

thanks
-- PMM

On Fri, 1 Feb 2019 at 14:50, 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.
> 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.
>
> 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
>   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

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

[Marc-André Lureau]

Hi

On Thu, Feb 14, 2019 at 12:30 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Ping! Thanks to Alex for doing low-level review of this patchset.

Overall, looks good to me too.

Minor nit: configure doesn't check presence of sphinx-build, and on my
fc29, it's sphinx-build-3 :)

CI files will probably need to be updated.

> I'm particularly interested in high-level review:
>  * is this the right way to be going?
>  * if we committed this and then did a release with the
>    docs as they are like this, would that be ok?

Certainly, it can improve over time imho.

>  * what's the most important next step after this?
>

For me the next steps are:

- merge your series! :)

- integrate the texi doc somehow (apparently Paolo had some solution),
or convert the texi doc to rst (modiy texi2any to do that?)

- have the docs hosted on www.qemu.org, with some stability (ideally,
we could share links to a specific doc, say a QMP command or an
internal API, that would remain stable).

  I wonder why Daniel qemu-web patches aren't yet merged. I remember
some questions regarding doc import and automation. There will be a
similar problem with sphinx doc.

  (gitlab makes this fairly easy with CI artifcats, fwiw ;-)

- convert more of our doc to rst

- add kerneldoc

- improve the style, for consistency with qemu.org style



> thanks
> -- PMM
>
> On Fri, 1 Feb 2019 at 14:50, 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.
> > 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.
> >
> > 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
> >   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

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

[Peter Maydell]

On Thu, 14 Feb 2019 at 14:56, Marc-André Lureau
<marcandre.lureau@redhat.com> wrote:
>
> Hi
>
> On Thu, Feb 14, 2019 at 12:30 PM Peter Maydell <peter.maydell@linaro.org> wrote:
> >
> > Ping! Thanks to Alex for doing low-level review of this patchset.
>
> Overall, looks good to me too.
>
> Minor nit: configure doesn't check presence of sphinx-build, and on my
> fc29, it's sphinx-build-3 :)

It does check, but I forgot to make the makefiles pay attention
to the check.

That's very irritating that Fedora is using a weird filename for
the tool -- what is their justification for doing that?
I suppose we'll have to make configure cope :-(

>
> CI files will probably need to be updated.
>
> > I'm particularly interested in high-level review:
> >  * is this the right way to be going?
> >  * if we committed this and then did a release with the
> >    docs as they are like this, would that be ok?
>
> Certainly, it can improve over time imho.
>
> >  * what's the most important next step after this?
> >
>
> For me the next steps are:
>
> - merge your series! :)
>
> - integrate the texi doc somehow (apparently Paolo had some solution),
> or convert the texi doc to rst (modiy texi2any to do that?)
>
> - have the docs hosted on www.qemu.org, with some stability (ideally,
> we could share links to a specific doc, say a QMP command or an
> internal API, that would remain stable).
>
>   I wonder why Daniel qemu-web patches aren't yet merged. I remember
> some questions regarding doc import and automation. There will be a
> similar problem with sphinx doc.
>
>   (gitlab makes this fairly easy with CI artifcats, fwiw ;-)
>
> - convert more of our doc to rst
>
> - add kerneldoc
>
> - improve the style, for consistency with qemu.org style

Thanks for the suggestions.

-- PMM

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

[Paolo Bonzini]

On 14/02/19 16:24, Peter Maydell wrote:
> It does check, but I forgot to make the makefiles pay attention
> to the check.
> 
> That's very irritating that Fedora is using a weird filename for
> the tool -- what is their justification for doing that?
> I suppose we'll have to make configure cope :-(

They do have sphinx-build but it uses Python 2.  If you only install the
Python 3 version, you get sphinx-build-3.

I think it will be switched in Fedora 30, but I'm not sure.

Paolo

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

[Peter Maydell]

On Thu, 14 Feb 2019 at 18:46, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 14/02/19 16:24, Peter Maydell wrote:
> > It does check, but I forgot to make the makefiles pay attention
> > to the check.
> >
> > That's very irritating that Fedora is using a weird filename for
> > the tool -- what is their justification for doing that?
> > I suppose we'll have to make configure cope :-(
>
> They do have sphinx-build but it uses Python 2.  If you only install the
> Python 3 version, you get sphinx-build-3

OK, so we could just make configure require "sphinx-build"
and fall back to "no docs if you don't have the tool";
that's not so bad.

thanks
-- PMM

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

[Peter Maydell]

On Fri, 1 Feb 2019 at 16:43, Alex Bennée <alex.bennee@linaro.org> wrote:
>
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > 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.
>
> I'm not sure what the title means... is the theme a reference to a
> layout? I thought themes were colours and other such visual frippery
> rather than actual content layout. But what do I know as a mere code
> monkey...

Just noticed I never followed up to this. Sphinx themes
allow a bit more customisation than just "colours and fonts":
they can also do layout things like changing up what sorts of
sidebar information is shown, or indeed whether there's any
kind of sidebar at all. Specific themes might expose some
theme-specific config options which allow tweaking of how
they appear.

http://www.sphinx-doc.org/en/stable/theming.html
has a few screenshots and gives more of an idea of what
sort of tweaks the theming system allows.

thanks
-- PMM