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

[Qemu-devel] [PATCH v3 00/12] 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.

Version 3 is almost the same as version 2: the only
differences are:
 * patch 5 enabling the Alabaster theme also adds
   "needs_sphinx = '1.3'" to docs/conf.py, since that is
   where the Alabaster theme was added to Sphinx proper
 * patch 9 has a new has_sphinx_build() function which
   specifically tests that sphinx-build can handle our
   conf.py, rather than just testing the executable
   is present
 * patch 9 adds /.doctrees to the .gitignore
 * patch 12 is new and provides a MAINTAINERS entry
   for the conf.py files (ie the build infrastructure,
   as distinct from the content)

I figured the changes in patches 5 and 9 were small enough
that I've kept the various reviewed/tested/etc tags.

thanks
-- PMM

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

 configure                             |  15 +-
 Makefile                              |  78 +++++++---
 .gitignore                            |   1 +
 MAINTAINERS                           |   6 +
 docs/conf.py                          | 216 ++++++++++++++++++++++++++
 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 +++
 12 files changed, 449 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 v3 01/12] docs/cpu-hotplug.rst: Fix rST markup issues

[Peter Maydell]

sphinx-build complains:

docs/cpu-hotplug.rst:67: ERROR: Unexpected indentation.
docs/cpu-hotplug.rst:69: ERROR: Unexpected indentation.
docs/cpu-hotplug.rst:74: WARNING: Block quote ends without a blank line; unexpected unindent.
docs/cpu-hotplug.rst:75: WARNING: Block quote ends without a blank line; unexpected unindent.
docs/cpu-hotplug.rst:76: SEVERE: Unexpected section title.

}
{
docs/cpu-hotplug.rst:78: WARNING: Block quote ends without a blank line; unexpected unindent.

These are the result of not indicating one of the literal
blocks by finishing the preceding paragraph with the "::" marker.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-2-peter.maydell@linaro.org
---
 docs/cpu-hotplug.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cpu-hotplug.rst b/docs/cpu-hotplug.rst
index 1c268e00b41..e2d4e893b01 100644
--- a/docs/cpu-hotplug.rst
+++ b/docs/cpu-hotplug.rst
@@ -60,7 +60,7 @@ vCPU hotplug
     hot-plugged (no "qom-path" member).  From its output in step (3), we
     can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0,
     while hot-plugging a CPU into socket 1 requires passing the listed
-    properties to QMP ``device_add``:
+    properties to QMP ``device_add``::
 
       (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0
       {
-- 
2.20.1

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

[Peter Maydell]

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

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-3-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 v3 03/12] docs: Commit initial files from sphinx-quickstart

[Peter Maydell]

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-4-peter.maydell@linaro.org
---
 docs/conf.py   | 168 +++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst |  20 ++++++
 2 files changed, 188 insertions(+)
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst

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

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

[Peter Maydell]

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-5-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 v3 05/12] 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.

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-6-peter.maydell@linaro.org
---
 docs/conf.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index e1d08a34a65..d118757cbd3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,7 +25,8 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+# 1.3 is where the 'alabaster' theme was shipped with Sphinx.
+needs_sphinx = '1.3'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -106,7 +107,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 v3 06/12] docs/conf.py: Don't include rST sources in HTML build

[Peter Maydell]

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-7-peter.maydell@linaro.org
---
 docs/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index d118757cbd3..d3018bc5395 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -113,6 +113,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 v3 07/12] docs/conf.py: Disable option warnings

[Peter Maydell]

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

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-8-peter.maydell@linaro.org
---
 docs/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index d3018bc5395..56a74e0fcb3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -77,6 +77,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 v3 08/12] docs: Provide separate conf.py for each manual we want

[Peter Maydell]

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

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

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

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-9-peter.maydell@linaro.org
---
 docs/conf.py           | 37 +++++++++++++++++++++++++++++++------
 docs/devel/conf.py     | 15 +++++++++++++++
 docs/devel/index.rst   | 21 +++++++++++++++++++++
 docs/index.rst         |  9 ++-------
 docs/interop/conf.py   | 15 +++++++++++++++
 docs/interop/index.rst | 18 ++++++++++++++++++
 6 files changed, 102 insertions(+), 13 deletions(-)
 create mode 100644 docs/devel/conf.py
 create mode 100644 docs/devel/index.rst
 create mode 100644 docs/interop/conf.py
 create mode 100644 docs/interop/index.rst

diff --git a/docs/conf.py b/docs/conf.py
index 56a74e0fcb3..f452e424cfe 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 ------------------------------------------------
@@ -91,8 +114,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 v3 09/12] 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>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-10-peter.maydell@linaro.org
---
 configure  | 15 +++++++++++++--
 Makefile   | 45 ++++++++++++++++++++++++++++++++++++++++++---
 .gitignore |  1 +
 3 files changed, 56 insertions(+), 5 deletions(-)

diff --git a/configure b/configure
index cefeb8fcce4..47bf617fcc5 100755
--- a/configure
+++ b/configure
@@ -4589,13 +4589,24 @@ if compile_prog "" "" ; then
   syncfs=yes
 fi
 
+# Check we have a new enough version of sphinx-build
+has_sphinx_build() {
+    # This is a bit awkward but works: create a trivial document and
+    # try to run it with our configuration file (which enforces a
+    # version requirement). This will fail if either
+    # sphinx-build doesn't exist at all or if it is too old.
+    mkdir -p "$TMPDIR1/sphinx"
+    touch "$TMPDIR1/sphinx/index.rst"
+    sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
+}
+
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has makeinfo && has pod2man; 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 2208bde4196..add22cf2947 100644
--- a/Makefile
+++ b/Makefile
@@ -388,7 +388,7 @@ dummy := $(call unnest-vars,, \
 
 include $(SRC_PATH)/tests/Makefile.include
 
-all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
+all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules
 
 qemu-version.h: FORCE
 	$(call quiet-command, \
@@ -637,6 +637,14 @@ dist: qemu-$(VERSION).tar.bz2
 qemu-%.tar.bz2:
 	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
 
+# Note that these commands assume that there are no HTML files in
+# the docs subdir in the source tree! If there are then this will
+# blow them away for an in-source-tree 'make clean'.
+define clean-manual =
+rm -rf docs/$1/_static
+rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html
+endef
+
 distclean: clean
 	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
 	rm -f config-all-devices.mak config-all-disas.mak config.status
@@ -657,6 +665,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
@@ -690,7 +701,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)"
@@ -841,6 +863,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","$@")
 
@@ -869,7 +908,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
diff --git a/.gitignore b/.gitignore
index b66b7725512..77522561b8e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+/.doctrees
 /config-devices.*
 /config-all-devices.*
 /config-all-disas.*
-- 
2.20.1

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

[Peter Maydell]

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-11-peter.maydell@linaro.org
---
 Makefile | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

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

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

[Peter Maydell]

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-12-peter.maydell@linaro.org
---
 Makefile     |  2 +-
 docs/conf.py | 21 ++++++++++++++++-----
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Makefile b/Makefile
index 0f5fdc2d2b2..6b3732d114f 100644
--- a/Makefile
+++ b/Makefile
@@ -869,7 +869,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 f452e424cfe..befbcc6c3e1 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -76,11 +76,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

[Qemu-devel] [PATCH v3 12/12] MAINTAINERS: Add entry for Sphinx documentation infrastructure

[Peter Maydell]

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 MAINTAINERS | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 5040d9dfb12..074ad46d473 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2567,3 +2567,9 @@ GIT submodules
 M: Daniel P. Berrange <berrange@redhat.com>
 S: Odd Fixes
 F: scripts/git-submodule.sh
+
+Sphinx documentation configuration and build machinery
+M: Peter Maydell <peter.maydell@linaro.org>
+S: Maintained
+F: docs/conf.py
+F: docs/*/conf.py
-- 
2.20.1

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

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190305172139.32662-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: 20190305172139.32662-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs

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

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 * [new tag]               patchew/20190305172139.32662-1-peter.maydell@linaro.org -> patchew/20190305172139.32662-1-peter.maydell@linaro.org
Switched to a new branch 'test'
ce1bbf4592 MAINTAINERS: Add entry for Sphinx documentation infrastructure
58caba19e5 docs/conf.py: Don't hard-code QEMU version
a1117b70fb Makefile: Abstract out "identify the pkgversion" code
dd1825f2bb Makefile, configure: Support building rST documentation
3d50302ccc docs: Provide separate conf.py for each manual we want
6820af85f7 docs/conf.py: Disable option warnings
d7b360ddee docs/conf.py: Don't include rST sources in HTML build
388d2c8ace docs/conf.py: Configure the 'alabaster' theme
b9c5183917 docs/conf.py: Disable unused _static directory
ad9f472e30 docs: Commit initial files from sphinx-quickstart
17772cd66c docs: Convert memory.txt to rst format
c700fc8d42 docs/cpu-hotplug.rst: Fix rST markup issues

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

9/12 Checking commit dd1825f2bb81 (Makefile, configure: Support building rST documentation)
10/12 Checking commit a1117b70fbc9 (Makefile: Abstract out "identify the pkgversion" code)
11/12 Checking commit 58caba19e578 (docs/conf.py: Don't hard-code QEMU version)
12/12 Checking commit ce1bbf459216 (MAINTAINERS: Add entry for Sphinx documentation infrastructure)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190305172139.32662-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 v3 12/12] MAINTAINERS: Add entry for Sphinx documentation infrastructure

[Philippe Mathieu-Daudé]

On 3/5/19 6:21 PM, Peter Maydell wrote:
> Add a MAINTAINERS entry for Sphinx documentation infrastructure:
> this doesn't cover actual content, only the machinery we use to
> build the docs.

Thanks!

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

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

> ---
>  MAINTAINERS | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 5040d9dfb12..074ad46d473 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2567,3 +2567,9 @@ GIT submodules
>  M: Daniel P. Berrange <berrange@redhat.com>
>  S: Odd Fixes
>  F: scripts/git-submodule.sh
> +
> +Sphinx documentation configuration and build machinery
> +M: Peter Maydell <peter.maydell@linaro.org>
> +S: Maintained
> +F: docs/conf.py
> +F: docs/*/conf.py
> 

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

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190305172139.32662-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: 20190305172139.32662-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs

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

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190305172139.32662-1-peter.maydell@linaro.org -> patchew/20190305172139.32662-1-peter.maydell@linaro.org
Switched to a new branch 'test'
f59fe29d7f MAINTAINERS: Add entry for Sphinx documentation infrastructure
7b59b19041 docs/conf.py: Don't hard-code QEMU version
b8f77058ec Makefile: Abstract out "identify the pkgversion" code
0c6c2fd3a4 Makefile, configure: Support building rST documentation
c88e10b0b6 docs: Provide separate conf.py for each manual we want
e30b5a56f7 docs/conf.py: Disable option warnings
3496ee67d6 docs/conf.py: Don't include rST sources in HTML build
0497f605d2 docs/conf.py: Configure the 'alabaster' theme
e343602608 docs/conf.py: Disable unused _static directory
b8eb65afb7 docs: Commit initial files from sphinx-quickstart
feb8ecbcdd docs: Convert memory.txt to rst format
649b8be5bd docs/cpu-hotplug.rst: Fix rST markup issues

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

9/12 Checking commit 0c6c2fd3a464 (Makefile, configure: Support building rST documentation)
10/12 Checking commit b8f77058ec91 (Makefile: Abstract out "identify the pkgversion" code)
11/12 Checking commit 7b59b1904103 (docs/conf.py: Don't hard-code QEMU version)
12/12 Checking commit f59fe29d7f9a (MAINTAINERS: Add entry for Sphinx documentation infrastructure)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190305172139.32662-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 v3 10/12] Makefile: Abstract out "identify the pkgversion" code

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> +  if test -d .git; then \

As mentioned somewhere else this week, test -e, since .git may be a file.

Otherwise,
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> sphinx-build complains:
> 
> docs/cpu-hotplug.rst:67: ERROR: Unexpected indentation.
> docs/cpu-hotplug.rst:69: ERROR: Unexpected indentation.
> docs/cpu-hotplug.rst:74: WARNING: Block quote ends without a blank line; unexpected unindent.
> docs/cpu-hotplug.rst:75: WARNING: Block quote ends without a blank line; unexpected unindent.
> docs/cpu-hotplug.rst:76: SEVERE: Unexpected section title.
> 
> }
> {
> docs/cpu-hotplug.rst:78: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> These are the result of not indicating one of the literal
> blocks by finishing the preceding paragraph with the "::" marker.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-2-peter.maydell@linaro.org
> ---
>  docs/cpu-hotplug.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> Commit the initial Sphinx conf.py and skeleton index.rst as
> generated with sphinx-quickstart. We'll update these to
> add QEMU-specific tweaks in subsequent commits.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-4-peter.maydell@linaro.org
> ---
>  docs/conf.py   | 168 +++++++++++++++++++++++++++++++++++++++++++++++++
>  docs/index.rst |  20 ++++++
>  2 files changed, 188 insertions(+)
>  create mode 100644 docs/conf.py
>  create mode 100644 docs/index.rst

Acked-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> 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>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-5-peter.maydell@linaro.org
> ---
>  docs/conf.py | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> 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>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-3-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%)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> 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>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-7-peter.maydell@linaro.org
> ---
>  docs/conf.py | 3 +++
>  1 file changed, 3 insertions(+)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> 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>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-8-peter.maydell@linaro.org
> ---
>  docs/conf.py | 3 +++
>  1 file changed, 3 insertions(+)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> Add support to our configure and makefile machinery for building
> our rST docs into HTML files.
> 
> Building the documentation now requires that sphinx-build is
> available; this seems better than allowing half the docs to
> be built if it is not present but having half of them missing.
> (In particular it means that assuming that distros configured with
> --enable-docs they'll get a helpful error from configure telling
> them the new build dependency.)
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-10-peter.maydell@linaro.org
> ---
>  configure  | 15 +++++++++++++--
>  Makefile   | 45 ++++++++++++++++++++++++++++++++++++++++++---
>  .gitignore |  1 +
>  3 files changed, 56 insertions(+), 5 deletions(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> Don't hard-code the QEMU version number into conf.py. Instead
> we either pass it to sphinx-build on the command line, or
> (if doing a standalone Sphinx run in a readthedocs.org setup)
> extract it from the VERSION file.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-12-peter.maydell@linaro.org
> ---
>  Makefile     |  2 +-
>  docs/conf.py | 21 ++++++++++++++++-----
>  2 files changed, 17 insertions(+), 6 deletions(-)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

Re: [Qemu-devel] [PATCH v3 12/12] MAINTAINERS: Add entry for Sphinx documentation infrastructure

[Richard Henderson]

On 3/5/19 9:21 AM, Peter Maydell wrote:
> Add a MAINTAINERS entry for Sphinx documentation infrastructure:
> this doesn't cover actual content, only the machinery we use to
> build the docs.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  MAINTAINERS | 6 ++++++
>  1 file changed, 6 insertions(+)

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>


r~

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

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190305172139.32662-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: 20190305172139.32662-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs

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

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190305172139.32662-1-peter.maydell@linaro.org -> patchew/20190305172139.32662-1-peter.maydell@linaro.org
Switched to a new branch 'test'
b37e0e545d MAINTAINERS: Add entry for Sphinx documentation infrastructure
6c63356b8d docs/conf.py: Don't hard-code QEMU version
f681007dea Makefile: Abstract out "identify the pkgversion" code
68cf6d5ae1 Makefile, configure: Support building rST documentation
902daac77e docs: Provide separate conf.py for each manual we want
fe2d476636 docs/conf.py: Disable option warnings
6379a4387d docs/conf.py: Don't include rST sources in HTML build
ecd2cccf77 docs/conf.py: Configure the 'alabaster' theme
81c5787a7f docs/conf.py: Disable unused _static directory
fd913234b4 docs: Commit initial files from sphinx-quickstart
6638912038 docs: Convert memory.txt to rst format
dc98fa5ed7 docs/cpu-hotplug.rst: Fix rST markup issues

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

9/12 Checking commit 68cf6d5ae1d7 (Makefile, configure: Support building rST documentation)
10/12 Checking commit f681007dea19 (Makefile: Abstract out "identify the pkgversion" code)
11/12 Checking commit 6c63356b8dde (docs/conf.py: Don't hard-code QEMU version)
12/12 Checking commit b37e0e545de1 (MAINTAINERS: Add entry for Sphinx documentation infrastructure)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190305172139.32662-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 v3 00/12] Enable build and install of our rST docs

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190305172139.32662-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: 20190305172139.32662-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs

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

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190305172139.32662-1-peter.maydell@linaro.org -> patchew/20190305172139.32662-1-peter.maydell@linaro.org
Switched to a new branch 'test'
735537a7f4 MAINTAINERS: Add entry for Sphinx documentation infrastructure
4428fbad0a docs/conf.py: Don't hard-code QEMU version
89b5d0e749 Makefile: Abstract out "identify the pkgversion" code
cfe0287a58 Makefile, configure: Support building rST documentation
5c3ec2cdfa docs: Provide separate conf.py for each manual we want
d8042c9b50 docs/conf.py: Disable option warnings
4cdaf3004d docs/conf.py: Don't include rST sources in HTML build
5c61204f5c docs/conf.py: Configure the 'alabaster' theme
41dbc87c87 docs/conf.py: Disable unused _static directory
54efc64218 docs: Commit initial files from sphinx-quickstart
3dfd59aa3c docs: Convert memory.txt to rst format
e5881b5de1 docs/cpu-hotplug.rst: Fix rST markup issues

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

9/12 Checking commit cfe0287a5826 (Makefile, configure: Support building rST documentation)
10/12 Checking commit 89b5d0e74995 (Makefile: Abstract out "identify the pkgversion" code)
11/12 Checking commit 4428fbad0abc (docs/conf.py: Don't hard-code QEMU version)
12/12 Checking commit 735537a7f4be (MAINTAINERS: Add entry for Sphinx documentation infrastructure)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190305172139.32662-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 v3 01/12] docs/cpu-hotplug.rst: Fix rST markup issues

[Cleber Rosa]

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

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

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

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

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

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

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

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

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190305172139.32662-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: 20190305172139.32662-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs

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

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190305172139.32662-1-peter.maydell@linaro.org -> patchew/20190305172139.32662-1-peter.maydell@linaro.org
Switched to a new branch 'test'
98332a76a6 MAINTAINERS: Add entry for Sphinx documentation infrastructure
41a1bddb55 docs/conf.py: Don't hard-code QEMU version
8d47807639 Makefile: Abstract out "identify the pkgversion" code
0ce9501263 Makefile, configure: Support building rST documentation
4f8f49b342 docs: Provide separate conf.py for each manual we want
ca6e04cc86 docs/conf.py: Disable option warnings
4ded0d2923 docs/conf.py: Don't include rST sources in HTML build
4c961752ab docs/conf.py: Configure the 'alabaster' theme
3ab58c3a86 docs/conf.py: Disable unused _static directory
7c7d95d884 docs: Commit initial files from sphinx-quickstart
50d1a0524d docs: Convert memory.txt to rst format
b0ae0aef73 docs/cpu-hotplug.rst: Fix rST markup issues

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

9/12 Checking commit 0ce950126364 (Makefile, configure: Support building rST documentation)
10/12 Checking commit 8d4780763945 (Makefile: Abstract out "identify the pkgversion" code)
11/12 Checking commit 41a1bddb55b5 (docs/conf.py: Don't hard-code QEMU version)
12/12 Checking commit 98332a76a6b7 (MAINTAINERS: Add entry for Sphinx documentation infrastructure)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190305172139.32662-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 v3 02/12] docs: Convert memory.txt to rst format

[Cleber Rosa]

On Tue, Mar 05, 2019 at 05:21:29PM +0000, Peter Maydell wrote:
> 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>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> Message-id: 20190228145624.24885-3-peter.maydell@linaro.org

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

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

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190305172139.32662-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: 20190305172139.32662-1-peter.maydell@linaro.org
Subject: [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs

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

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190305172139.32662-1-peter.maydell@linaro.org -> patchew/20190305172139.32662-1-peter.maydell@linaro.org
Switched to a new branch 'test'
36d6bf11a6 MAINTAINERS: Add entry for Sphinx documentation infrastructure
ea15377644 docs/conf.py: Don't hard-code QEMU version
55e30c7ac2 Makefile: Abstract out "identify the pkgversion" code
a94aea1a6b Makefile, configure: Support building rST documentation
aed640b8c6 docs: Provide separate conf.py for each manual we want
78927ee307 docs/conf.py: Disable option warnings
11a669fad0 docs/conf.py: Don't include rST sources in HTML build
060ecaed4f docs/conf.py: Configure the 'alabaster' theme
8d1c3f78ea docs/conf.py: Disable unused _static directory
9d5c1f7992 docs: Commit initial files from sphinx-quickstart
db8dfc0df5 docs: Convert memory.txt to rst format
791a4397a6 docs/cpu-hotplug.rst: Fix rST markup issues

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

9/12 Checking commit a94aea1a6b53 (Makefile, configure: Support building rST documentation)
10/12 Checking commit 55e30c7ac2b4 (Makefile: Abstract out "identify the pkgversion" code)
11/12 Checking commit ea1537764481 (docs/conf.py: Don't hard-code QEMU version)
12/12 Checking commit 36d6bf11a6fd (MAINTAINERS: Add entry for Sphinx documentation infrastructure)
=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190305172139.32662-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 v3 08/12] docs: Provide separate conf.py for each manual we want

[Cleber Rosa]

On Tue, Mar 05, 2019 at 05:21:35PM +0000, Peter Maydell wrote:
> By default Sphinx wants to build a single manual at once.
> For QEMU, this doesn't suit us, because we want to have
> separate manuals for "Developer's Guide", "User Manual",
> and so on, and we don't want to ship the Developer's Guide
> to end-users. However, we don't want to completely duplicate
> conf.py for each manual, and we'd like to continue to
> support "build all docs in one run" for third-party sites
> like readthedocs.org.
> 
> Make the top-level conf.py support two usage forms:
>  (1) as a common config file which is included by the conf.py
>  for each of QEMU's manuals: in this case sphinx-build is run
>  multiple times, once per subdirectory.
>  (2) as a top level conf file which will result in building all
>  the manuals into a single document: in this case sphinx-build is
>  run once, on the top-level docs directory.
> 
> Provide per-manual conf.py files and top level pages for
> our first two manuals:
>  * QEMU Developer's Guide (docs/devel)
>  * QEMU System Emulation Management and Interoperability Guide
>    (docs/interop)
>

I have the impression that this can be simplified by making use of
"only" tags:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only

So, conf.py could detect if it's being run on readthedocs.org:

  ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'

And manipulate the "tags" variable accordingly:

  if ON_RTD:
     tags.add('devel')
     tags.add('interop')

Then, on an index.rst, it could be a simple matter of:

.. only:: devel
================
Developers Guide
================
.. toctree::
   docs/devel

.. only:: interop
=============
Interop Guide
=============
.. toctree::
   docs/interop

.. only:: devel and interop
===============
QEMU Full Guide
===============
.. toctree::
   docs/devel
   docs/interop

Or some alternative layout.  Please beware that I haven't performed a
full examination of that (or similar) approach.

If that doesn't work, I'd consider having a top level "common.py",
whose contents are imported by the various "conf.py", instead of
exec()'d.  That I've tried, and a simple:

  from common import *
  release = 'overridden_value'

Works as expected and is respected by sphinx.

- Cleber.

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

[Peter Maydell]

On Thu, 7 Mar 2019 at 00:04, Cleber Rosa <crosa@redhat.com> wrote:
> But I'm assuming the extended sphinx roles/directives will be used, so
> the only way to check against future breakage would be to build the
> docs.
>
> Do we have strong position in favor or against putting that into the
> "common" `make check` flow?

Assuming the host has sphinx-build, the docs will be built as
part of "make", so actual errors will be caught. We should
add the sphinx-build flag to make warnings into errors in
the same way we use -Werror, but I wanted to get the series
into master first.

thanks
-- PMM

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

[Peter Maydell]

On Thu, 7 Mar 2019 at 01:40, Cleber Rosa <crosa@redhat.com> wrote:
> I have the impression that this can be simplified by making use of
> "only" tags:
>
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only
>
> So, conf.py could detect if it's being run on readthedocs.org:
>
>   ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
>
> And manipulate the "tags" variable accordingly:
>
>   if ON_RTD:
>      tags.add('devel')
>      tags.add('interop')
>
> Then, on an index.rst, it could be a simple matter of:
>
> .. only:: devel
> ================
> Developers Guide
> ================
> .. toctree::
>    docs/devel
>
> .. only:: interop
> =============
> Interop Guide
> =============
> .. toctree::
>    docs/interop
>
> .. only:: devel and interop
> ===============
> QEMU Full Guide
> ===============
> .. toctree::
>    docs/devel
>    docs/interop

Thanks for pointing out the tags functionality. That said,
this won't do what we want, will it?
 * building the docs gives all the docs in the build tree
 * but we only install via 'make install' the ones the user wants

thanks
-- PMM

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

[Cleber Rosa]

On Thu, Mar 07, 2019 at 09:47:18AM +0000, Peter Maydell wrote:
> On Thu, 7 Mar 2019 at 00:04, Cleber Rosa <crosa@redhat.com> wrote:
> > But I'm assuming the extended sphinx roles/directives will be used, so
> > the only way to check against future breakage would be to build the
> > docs.
> >
> > Do we have strong position in favor or against putting that into the
> > "common" `make check` flow?
> 
> Assuming the host has sphinx-build, the docs will be built as
> part of "make", so actual errors will be caught. We should

That's even better IMO.

> add the sphinx-build flag to make warnings into errors in
> the same way we use -Werror, but I wanted to get the series
> into master first.
>

Absolutely!

Regards,
- Cleber.

> thanks
> -- PMM

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

[Cleber Rosa]

On Thu, Mar 07, 2019 at 09:49:44AM +0000, Peter Maydell wrote:
> On Thu, 7 Mar 2019 at 01:40, Cleber Rosa <crosa@redhat.com> wrote:
> > I have the impression that this can be simplified by making use of
> > "only" tags:
> >
> > https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only
> >
> > So, conf.py could detect if it's being run on readthedocs.org:
> >
> >   ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
> >
> > And manipulate the "tags" variable accordingly:
> >
> >   if ON_RTD:
> >      tags.add('devel')
> >      tags.add('interop')
> >
> > Then, on an index.rst, it could be a simple matter of:
> >
> > .. only:: devel
> > ================
> > Developers Guide
> > ================
> > .. toctree::
> >    docs/devel
> >
> > .. only:: interop
> > =============
> > Interop Guide
> > =============
> > .. toctree::
> >    docs/interop
> >
> > .. only:: devel and interop
> > ===============
> > QEMU Full Guide
> > ===============
> > .. toctree::
> >    docs/devel
> >    docs/interop
> 
> Thanks for pointing out the tags functionality. That said,
> this won't do what we want, will it?
>  * building the docs gives all the docs in the build tree
>  * but we only install via 'make install' the ones the user wants
>

It should be doable.  I put a PoC here:

  https://github.com/clebergnu/sphinx-conditional-project/tree/master

I'm understanding that the `make install` step is nothing but a copy
of the produced build.  For this PoC, I used an HTML builder.

> thanks
> -- PMM

Regards,
- Cleber.

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

[Peter Maydell]

On Thu, 7 Mar 2019 at 12:14, Cleber Rosa <crosa@redhat.com> wrote:
>
> On Thu, Mar 07, 2019 at 09:49:44AM +0000, Peter Maydell wrote:
> > On Thu, 7 Mar 2019 at 01:40, Cleber Rosa <crosa@redhat.com> wrote:
> > Thanks for pointing out the tags functionality. That said,
> > this won't do what we want, will it?
> >  * building the docs gives all the docs in the build tree
> >  * but we only install via 'make install' the ones the user wants
> >
>
> It should be doable.  I put a PoC here:
>
>   https://github.com/clebergnu/sphinx-conditional-project/tree/master
>
> I'm understanding that the `make install` step is nothing but a copy
> of the produced build.  For this PoC, I used an HTML builder.

I'm still not clear how this helps. Either the top level
index file has everything in it (in which case it's no good
for 'make install'), or we just have separate manuals per
document (which doesn't seem to me to gain much over what
we currently have in this patchset, and you end up listing
everything multiple times in the index.rst).

thanks
-- PMM

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

[Cleber Rosa]

On Thu, Mar 07, 2019 at 12:29:08PM +0000, Peter Maydell wrote:
> On Thu, 7 Mar 2019 at 12:14, Cleber Rosa <crosa@redhat.com> wrote:
> >
> > On Thu, Mar 07, 2019 at 09:49:44AM +0000, Peter Maydell wrote:
> > > On Thu, 7 Mar 2019 at 01:40, Cleber Rosa <crosa@redhat.com> wrote:
> > > Thanks for pointing out the tags functionality. That said,
> > > this won't do what we want, will it?
> > >  * building the docs gives all the docs in the build tree
> > >  * but we only install via 'make install' the ones the user wants
> > >
> >
> > It should be doable.  I put a PoC here:
> >
> >   https://github.com/clebergnu/sphinx-conditional-project/tree/master
> >
> > I'm understanding that the `make install` step is nothing but a copy
> > of the produced build.  For this PoC, I used an HTML builder.
> 
> I'm still not clear how this helps. Either the top level
> index file has everything in it (in which case it's no good
> for 'make install'), or we just have separate manuals per

IIRC, it shouldn't matter what the "top level" index file (index.rst)
has, because it's the resulting build (not the source index.rst) that
will be 'make install'ed.  Or am I missing something?

> document (which doesn't seem to me to gain much over what
> we currently have in this patchset, and you end up listing
> everything multiple times in the index.rst).

I don't see the multiple listings you mention here, but I guess you're
referring to the "include" of the individual manual's index (devel.rst
and interop.rst in this example).  I chose to implement the logic for
choosing the content in the rst file, but an alternative would be to
do it in conf.py:

 if tags.has('devel'):
    master_doc = 'devel.rst'
 elif tags.has('interop'):
    master_doc = 'interop.rst'
 else:
    master_doc = 'index.rst'

IMO all options add a bit of poison (pick yours).  I do feel that the
tag approach reuses sphinx functionality, and thus facilitate
maintanance and minimize duplication.

Anyway, if it's not clear to you as it's to me, then I'm probably
biased or missing something.

> 
> thanks
> -- PMM

Best regards,
- Cleber.

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

[Peter Maydell]

On Thu, 7 Mar 2019 at 13:18, Cleber Rosa <crosa@redhat.com> wrote:
>
> On Thu, Mar 07, 2019 at 12:29:08PM +0000, Peter Maydell wrote:
> > I'm still not clear how this helps. Either the top level
> > index file has everything in it (in which case it's no good
> > for 'make install'), or we just have separate manuals per
>
> IIRC, it shouldn't matter what the "top level" index file (index.rst)
> has, because it's the resulting build (not the source index.rst) that
> will be 'make install'ed.  Or am I missing something?

I guess what I'm trying to ask is whether this tags
approach results in different (or differently structured)
final documents being produced, or whether it's just a
different mechanism that gives the same end result.

> I don't see the multiple listings you mention here

I think I was looking at the sketch you had in a previous
email rather than the more fleshed-out code in the git repo.

> Anyway, if it's not clear to you as it's to me, then I'm probably
> biased or missing something.

Well, I'm also a bit biased here, in that this is v3 of this
patchset that's been on the list using this approach for
a month, and I was planning to apply it to master today
so that it could be in before the softfreeze on Tuesday
next week. So late-breaking suggestions for significant
restructurings are essentially saying "we should postpone
this to 4.1" :-(

thanks
-- PMM

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

[Cleber Rosa]

On Thu, Mar 07, 2019 at 01:30:39PM +0000, Peter Maydell wrote:
> On Thu, 7 Mar 2019 at 13:18, Cleber Rosa <crosa@redhat.com> wrote:
> >
> > On Thu, Mar 07, 2019 at 12:29:08PM +0000, Peter Maydell wrote:
> > > I'm still not clear how this helps. Either the top level
> > > index file has everything in it (in which case it's no good
> > > for 'make install'), or we just have separate manuals per
> >
> > IIRC, it shouldn't matter what the "top level" index file (index.rst)
> > has, because it's the resulting build (not the source index.rst) that
> > will be 'make install'ed.  Or am I missing something?
> 
> I guess what I'm trying to ask is whether this tags
> approach results in different (or differently structured)
> final documents being produced, or whether it's just a
> different mechanism that gives the same end result.
>

I was pursuing the same result, as I understand the requirements are
sound and well defined, that is, we do want multiple final documents
produced in the non-readthedocs.org environment.

> > I don't see the multiple listings you mention here
> 
> I think I was looking at the sketch you had in a previous
> email rather than the more fleshed-out code in the git repo.
>

Oh, OK.

> > Anyway, if it's not clear to you as it's to me, then I'm probably
> > biased or missing something.
> 
> Well, I'm also a bit biased here, in that this is v3 of this
> patchset that's been on the list using this approach for
> a month, and I was planning to apply it to master today
> so that it could be in before the softfreeze on Tuesday
> next week. So late-breaking suggestions for significant
> restructurings are essentially saying "we should postpone
> this to 4.1" :-(
>

I apologize for not looking at this before... honestly speaking, my
bandwidth and efficiency doesn't allow me look at most patches :).  It
was only a CC on this v3 that caught my attention.

Anyway, I don't want to disrupt progress, and I do believe in
incremental betterment.  I have plans to add Python API docs once the
"python" directory structure gets in, so I might as well suggest
improvements in the form of patches later on.

Feel free to ignore this suggestion for now.

> thanks
> -- PMM

Best regards,
- Cleber.

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

[Peter Maydell]

On Thu, 7 Mar 2019 at 13:41, Cleber Rosa <crosa@redhat.com> wrote:
>
> On Thu, Mar 07, 2019 at 01:30:39PM +0000, Peter Maydell wrote:
> > Well, I'm also a bit biased here, in that this is v3 of this
> > patchset that's been on the list using this approach for
> > a month, and I was planning to apply it to master today
> > so that it could be in before the softfreeze on Tuesday
> > next week. So late-breaking suggestions for significant
> > restructurings are essentially saying "we should postpone
> > this to 4.1" :-(
> >
>
> I apologize for not looking at this before... honestly speaking, my
> bandwidth and efficiency doesn't allow me look at most patches :).  It
> was only a CC on this v3 that caught my attention.
>
> Anyway, I don't want to disrupt progress, and I do believe in
> incremental betterment.  I have plans to add Python API docs once the
> "python" directory structure gets in, so I might as well suggest
> improvements in the form of patches later on.

OK, thanks. If the end result in document structure is the
same then we can make the change as an incremental improvement later.

thanks
-- PMM

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

[Peter Maydell]

On Sat, 30 Mar 2019 at 22:05, Eric Blake <eblake@redhat.com> wrote:
> Rich told me that qemu-nbd.8 was not being built, and I confirmed that
> it failed to build for me. git bisect points to this commit as the
> reason that 'touch qemu-nbd.texi; make' no longer rebuilds qemu-nbd.8
> automatically. Is it merely because I don't have enough stuff installed,
> or is it an actual broken dependency?
>
> /me goes and runs 'dnf install "*/sphinx-build"...
>
> Nope, even with that installed, qemu-nbd.8 is still not getting built by
> 'make'; but 'make qemu-nbd.8' is working. We lost a dependency :(

I just did a test build from clean and I get a qemu-nbd.8 in the
build directory. I also  checked that 'touch qemu-nbd.texi; make -C build V=1'
rebuilds the manpage, and it does:

[snip other stuff]
perl -Ww -- /home/pm215/qemu/scripts/texi2pod.pl -I docs -I
/home/pm215/qemu -I . "-DVERSION=3.1.91"
/home/pm215/qemu/qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8
--section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8
[...]

You will need sphinx-build in order to build
the docs now, and without that we won't build the manpage, but
if you have sphinx-build installed then it should work.
Can you check that your config-host.mak has BUILD_DOCS=yes ?
Did you definitely rerun configure after installing sphinx?

thanks
-- PMM

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

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1875 bytes --]

On 4/1/19 2:58 AM, Peter Maydell wrote:
> On Sat, 30 Mar 2019 at 22:05, Eric Blake <eblake@redhat.com> wrote:
>> Rich told me that qemu-nbd.8 was not being built, and I confirmed that
>> it failed to build for me. git bisect points to this commit as the
>> reason that 'touch qemu-nbd.texi; make' no longer rebuilds qemu-nbd.8
>> automatically. Is it merely because I don't have enough stuff installed,
>> or is it an actual broken dependency?
>>
>> /me goes and runs 'dnf install "*/sphinx-build"...
>>
>> Nope, even with that installed, qemu-nbd.8 is still not getting built by
>> 'make'; but 'make qemu-nbd.8' is working. We lost a dependency :(
> 
> I just did a test build from clean and I get a qemu-nbd.8 in the
> build directory. I also  checked that 'touch qemu-nbd.texi; make -C build V=1'
> rebuilds the manpage, and it does:
> 
> [snip other stuff]
> perl -Ww -- /home/pm215/qemu/scripts/texi2pod.pl -I docs -I
> /home/pm215/qemu -I . "-DVERSION=3.1.91"
> /home/pm215/qemu/qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8
> --section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8
> [...]
> 
> You will need sphinx-build in order to build
> the docs now, and without that we won't build the manpage, but
> if you have sphinx-build installed then it should work.
> Can you check that your config-host.mak has BUILD_DOCS=yes ?

Not seeing it.

> Did you definitely rerun configure after installing sphinx?

Trying that again.  I did not specify anything special to configure to
force-enable/disable docs, so this time, it should auto-detect that
sphinx-build is present...

and now BUILD_DOCS=yes appears...

And that fixes it. Thanks for helping me spot the added build dependency.


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]