[PATCH 0/7] docs: State QEMU version and license in all HTML footers

[PATCH 0/7] docs: State QEMU version and license in all HTML footers

[Peter Maydell]

This patchset is an effort to fix something up which I promised
Markus I would do after we got the initial conversion to Sphinx
done. The old QAPI reference documentation noted the documentation
license in the texinfo source (but not in the generated HTML or
in the generated manpages); Sphinx generated docs currently don't.

The patchset starts with some tidyup that is possible now that
we have a single combined HTML manual rather than five separate ones.
Rather than putting common-to-all-QEMU info like the deprecation,
build and license pages into the "system" manual, we can move them
out to a new top level section which I have called "About". So that
the manual doesn't now start too abruptly, I've also added some
actual "about" text here (mostly cribbed or adapted from our website
or from other parts of the manual).

Secondly, it uses the Sphinx template-override functionality to
add more text to the footer added to each HTML page, which will
now read:

# © Copyright 2021, The QEMU Project Developers.
#
# Built with Sphinx using a theme provided by Read the Docs.
#
# This documentation is for QEMU version 6.0.50.
#
# QEMU and this manual are released under the GNU General Public License, version 2.

where the last line is a hyperlink to the about/license page.

I'm open to suggestions on:
 * name of the new top-level section
 * text wording
 * whether we need to have the version number in the footer
   (it's already in the sidebar under the QEMU logo, but this
   seemed a bit too inconspicious, so I added it to the footer
   since I was messing with it anyway)

You can find a built version of the docs at:
https://pm215.gitlab.io/-/qemu/-/jobs/1399259647/artifacts/public/index.html

I had a look at getting our manpages to also state the license,
but this is tricky due to various deficiencies in Sphinx.
(We never have stated the license in our manpages, so this isn't
a regression compared to the old texinfo setup.)

Markus: do you feel this series is sufficient that we can remove
the TODO lines in docs/interop/qemu-ga-ref.rst,
docs/interop/qemu-qmp-ref.rst and docs/interop/qemu-storage-daemon-qmp-ref.rst
as now being done?

thanks
-- PMM

Peter Maydell (7):
  docs: Fix documentation Copyright date
  docs: Stop calling the top level subsections of our manual 'manuals'
  docs: Remove "Contents:" lines from top-level subsections
  docs: Move deprecation, build and license info out of system/
  docs: Add some actual About text to about/index.rst
  docs: Add license note to the HTML page footer
  docs: Add QEMU version information to HTML footer

 docs/_templates/footer.html                 | 14 +++++++++++
 docs/{system => about}/build-platforms.rst  |  0
 docs/{system => about}/deprecated.rst       |  0
 docs/about/index.rst                        | 27 +++++++++++++++++++++
 docs/{system => about}/license.rst          |  0
 docs/{system => about}/removed-features.rst |  0
 docs/conf.py                                |  2 +-
 docs/devel/index.rst                        |  7 +-----
 docs/index.rst                              |  1 +
 docs/interop/index.rst                      |  9 ++-----
 docs/meson.build                            |  3 ++-
 docs/specs/index.rst                        |  7 ++----
 docs/system/index.rst                       | 11 +--------
 docs/tools/index.rst                        |  7 ++----
 docs/user/index.rst                         |  7 +-----
 MAINTAINERS                                 |  1 +
 16 files changed, 55 insertions(+), 41 deletions(-)
 create mode 100644 docs/_templates/footer.html
 rename docs/{system => about}/build-platforms.rst (100%)
 rename docs/{system => about}/deprecated.rst (100%)
 create mode 100644 docs/about/index.rst
 rename docs/{system => about}/license.rst (100%)
 rename docs/{system => about}/removed-features.rst (100%)

-- 
2.20.1

[PATCH 1/7] docs: Fix documentation Copyright date

[Peter Maydell]

In commit 6d8980a38fa we updated the copyright string we present to
the user in -version output, About dialogs, etc, but we forgot that
the Sphinx manuals have a separate copyright string setting.  Update
that one too.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 42729e22bbe..ff6e92c6e2e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -87,7 +87,7 @@
 
 # General information about the project.
 project = u'QEMU'
-copyright = u'2020, The QEMU Project Developers'
+copyright = u'2021, The QEMU Project Developers'
 author = u'The QEMU Project Developers'
 
 # The version info for the project you're documenting, acts as replacement for
-- 
2.20.1

[PATCH 2/7] docs: Stop calling the top level subsections of our manual 'manuals'

[Peter Maydell]

We merged our previous multiple-manual setup into a single Sphinx
manual, but we left some text in the various index.rst lines that
still calls the top level subsections separate 'manuals'.  Update
them to talk about "this section of the manual" instead, and remove
now-obsolete comments about how the index.rst files are the "top
level page for the 'foo' manual".

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst   | 5 +----
 docs/interop/index.rst | 7 ++-----
 docs/specs/index.rst   | 5 ++---
 docs/system/index.rst  | 5 +----
 docs/tools/index.rst   | 5 ++---
 docs/user/index.rst    | 5 +----
 6 files changed, 9 insertions(+), 23 deletions(-)

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 977c3893bda..e188f187a18 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -1,10 +1,7 @@
-.. This is the top level page for the 'devel' manual.
-
-
 Developer Information
 =====================
 
-This manual documents various parts of the internals of QEMU.
+This section of the 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.
 
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 219a5e5fc50..8b34da6f551 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -1,11 +1,8 @@
-.. This is the top level page for the 'interop' manual.
-
-
 System Emulation Management and Interoperability
 ================================================
 
-This manual contains documents and specifications that are useful
-for making QEMU interoperate with other software.
+This section of the manual contains documents and specifications that
+are useful for making QEMU interoperate with other software.
 
 Contents:
 
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 7b08314d334..4c0d2a37cb8 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -1,9 +1,8 @@
-.. This is the top level page for the 'specs' manual
-
-
 System Emulation Guest Hardware Specifications
 ==============================================
 
+This section of the manual contains specifications of
+guest hardware that is specific to QEMU.
 
 Contents:
 
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 6092eb2d91d..2a9bd759807 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -1,10 +1,7 @@
-.. This is the top level page for the 'system' manual.
-
-
 System Emulation
 ================
 
-This manual is the overall guide for users using QEMU
+This section of the manual is the overall guide for users using QEMU
 for full system emulation (as opposed to user-mode emulation).
 This includes working with hypervisors such as KVM, Xen, Hax
 or Hypervisor.Framework.
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index d923834a739..ffb14b9690b 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -1,9 +1,8 @@
-.. This is the top level page for the 'tools' manual
-
-
 Tools
 =====
 
+This section of the manual documents QEMU's "tools": its
+command line utilities and other standalone programs.
 
 Contents:
 
diff --git a/docs/user/index.rst b/docs/user/index.rst
index a5b47459ec7..6ac2ac089fd 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -1,10 +1,7 @@
-.. This is the top level page for the 'user' manual.
-
-
 User Mode Emulation
 ===================
 
-This manual is the overall guide for users using QEMU
+This section of the manual is the overall guide for users using QEMU
 for user-mode emulation.  In this mode, QEMU can launch
 processes compiled for one CPU on another CPU.
 
-- 
2.20.1

[PATCH 3/7] docs: Remove "Contents:" lines from top-level subsections

[Peter Maydell]

Since the top-level subsections aren't self-contained manuals
any more, the "Contents:" lines at the top of each of their
index pages look a bit odd; remove them.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/devel/index.rst   | 2 --
 docs/interop/index.rst | 2 --
 docs/specs/index.rst   | 2 --
 docs/system/index.rst  | 2 --
 docs/tools/index.rst   | 2 --
 docs/user/index.rst    | 2 --
 6 files changed, 12 deletions(-)

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index e188f187a18..ff43ba78958 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -5,8 +5,6 @@ This section of the 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
    :includehidden:
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index 8b34da6f551..b1bab81e2ee 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -4,8 +4,6 @@ System Emulation Management and Interoperability
 This section of the manual contains documents and specifications that
 are useful for making QEMU interoperate with other software.
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 4c0d2a37cb8..b7b08ea30d7 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -4,8 +4,6 @@ System Emulation Guest Hardware Specifications
 This section of the manual contains specifications of
 guest hardware that is specific to QEMU.
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 2a9bd759807..058cabd36cc 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -6,8 +6,6 @@ for full system emulation (as opposed to user-mode emulation).
 This includes working with hypervisors such as KVM, Xen, Hax
 or Hypervisor.Framework.
 
-Contents:
-
 .. toctree::
    :maxdepth: 3
 
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index ffb14b9690b..ef6041a490f 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -4,8 +4,6 @@ Tools
 This section of the manual documents QEMU's "tools": its
 command line utilities and other standalone programs.
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 6ac2ac089fd..9faa4badd78 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -5,8 +5,6 @@ This section of the manual is the overall guide for users using QEMU
 for user-mode emulation.  In this mode, QEMU can launch
 processes compiled for one CPU on another CPU.
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
-- 
2.20.1

[PATCH 4/7] docs: Move deprecation, build and license info out of system/

[Peter Maydell]

Now that we have a single Sphinx manual rather than multiple manuals,
we can provide a better place for "common to all of QEMU" information
like the deprecation notices, build platforms, license information,
which we currently have in the system/ manual even though it applies
to all of QEMU.

Create a new directory about/ on the same level as system/, user/,
etc, and move these documents there.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/{system => about}/build-platforms.rst  |  0
 docs/{system => about}/deprecated.rst       |  0
 docs/about/index.rst                        | 10 ++++++++++
 docs/{system => about}/license.rst          |  0
 docs/{system => about}/removed-features.rst |  0
 docs/index.rst                              |  1 +
 docs/system/index.rst                       |  4 ----
 7 files changed, 11 insertions(+), 4 deletions(-)
 rename docs/{system => about}/build-platforms.rst (100%)
 rename docs/{system => about}/deprecated.rst (100%)
 create mode 100644 docs/about/index.rst
 rename docs/{system => about}/license.rst (100%)
 rename docs/{system => about}/removed-features.rst (100%)

diff --git a/docs/system/build-platforms.rst b/docs/about/build-platforms.rst
similarity index 100%
rename from docs/system/build-platforms.rst
rename to docs/about/build-platforms.rst
diff --git a/docs/system/deprecated.rst b/docs/about/deprecated.rst
similarity index 100%
rename from docs/system/deprecated.rst
rename to docs/about/deprecated.rst
diff --git a/docs/about/index.rst b/docs/about/index.rst
new file mode 100644
index 00000000000..cd44456a6bf
--- /dev/null
+++ b/docs/about/index.rst
@@ -0,0 +1,10 @@
+About QEMU
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   build-platforms
+   deprecated
+   removed-features
+   license
diff --git a/docs/system/license.rst b/docs/about/license.rst
similarity index 100%
rename from docs/system/license.rst
rename to docs/about/license.rst
diff --git a/docs/system/removed-features.rst b/docs/about/removed-features.rst
similarity index 100%
rename from docs/system/removed-features.rst
rename to docs/about/removed-features.rst
diff --git a/docs/index.rst b/docs/index.rst
index 763e3d0426e..5f7eaaa632c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,7 @@ Welcome to QEMU's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   about/index
    system/index
    user/index
    tools/index
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 058cabd36cc..fda4b1b7054 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -35,7 +35,3 @@ or Hypervisor.Framework.
    targets
    security
    multi-process
-   deprecated
-   removed-features
-   build-platforms
-   license
-- 
2.20.1

[PATCH 5/7] docs: Add some actual About text to about/index.rst

[Peter Maydell]

Add some text to About to act as a brief introduction to the QEMU
manual and to make the about page a bit less of an abrupt start to
it.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/about/index.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/about/index.rst b/docs/about/index.rst
index cd44456a6bf..689a9861dc3 100644
--- a/docs/about/index.rst
+++ b/docs/about/index.rst
@@ -1,6 +1,23 @@
 About QEMU
 ==========
 
+QEMU is a generic and open source machine emulator and virtualizer.
+
+QEMU can be used in several different ways. The most common is for
+"system emulation", where it provides a virtual model of an
+entire machine (CPU, memory and emulated devices) to run a guest OS.
+In this mode the CPU may be fully emulated, or it may work with
+a hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to
+allow the guest to run directly on the host CPU.
+
+The second supported way to use QEMU is "user mode emulation",
+where QEMU can launch processes compiled for one CPU on another CPU.
+In this mode the CPU is always emulated.
+
+QEMU also provides a number of standalone commandline utilities,
+such as the `qemu-img` disk image utility that allows you to create,
+convert and modify disk images.
+
 .. toctree::
    :maxdepth: 2
 
-- 
2.20.1

[PATCH 6/7] docs: Add license note to the HTML page footer

[Peter Maydell]

The standard Sphinx/RTD HTML page footer gives a copyright line
(based on the 'copyright' variable set in conf.py) and a line "Built
with Sphinx using a theme provided by Read the Docs" (which can be
disabled via the html_show_sphinx variable, but we leave it enabled).
As a free software project, we'd like to also mention the license
QEMU and its manual are released under.

Add a template footer.html which defines the 'extrafooter' block that
the RtD theme provides for this purpose.  The new line of text will
go below the existing copyright and sphinx-acknowledgement lines.
(Unfortunately the RTD footer template does not permit putting it
after the copyright but before the sphinx-acknowledgement.)

We use the templating functionality to make the new text also be a
hyperlink to the about/license.html page of the manual.

Unlike rst files, HTML template files are not reported to our depfile
plugin, so we maintain a manual list in meson.build.  New template
files should be rare, so not being able to auto-generate the
dependency info is not too awkward.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
I know nothing about Jinja, and have merely cargo-culted the
"make a link to a document" stuff from the handling of the
optional copyright link in /usr/share/sphinx_rtd_theme/footer.html ...
---
 docs/_templates/footer.html | 12 ++++++++++++
 docs/meson.build            |  3 ++-
 MAINTAINERS                 |  1 +
 3 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 docs/_templates/footer.html

diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html
new file mode 100644
index 00000000000..4c15e17d2a8
--- /dev/null
+++ b/docs/_templates/footer.html
@@ -0,0 +1,12 @@
+{% extends "!footer.html" %}
+{% block extrafooter %}
+
+<!-- Empty para to force a blank line after "Built with Sphinx ..." -->
+<p></p>
+
+{% trans path=pathto('about/license') %}
+<p><a href="{{ path }}">QEMU and this manual are released under the
+GNU General Public License, version 2.</a></p>
+{% endtrans %}
+{{ super() }}
+{% endblock %}
diff --git a/docs/meson.build b/docs/meson.build
index 855e3916e90..300b1343291 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -44,6 +44,7 @@ if build_docs
                           meson.source_root() / 'docs/sphinx/qapidoc.py',
                           meson.source_root() / 'docs/sphinx/qmp_lexer.py',
                           qapi_gen_depends ]
+  sphinx_template_files = [ meson.source_root() / 'docs/_templates/footer.html' ]
 
   have_ga = have_tools and config_host.has_key('CONFIG_GUEST_AGENT')
 
@@ -76,7 +77,7 @@ if build_docs
                 output: 'docs.stamp',
                 input: files('conf.py'),
                 depfile: 'docs.d',
-                depend_files: sphinx_extn_depends,
+                depend_files: [ sphinx_extn_depends, sphinx_template_files ],
                 command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@',
                           '-Ddepfile_stamp=@OUTPUT0@',
                           '-b', 'html', '-d', private_dir,
diff --git a/MAINTAINERS b/MAINTAINERS
index cfbf7ef79bc..790d857f6c7 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3410,6 +3410,7 @@ S: Maintained
 F: docs/conf.py
 F: docs/*/conf.py
 F: docs/sphinx/
+F: docs/_templates/
 
 Miscellaneous
 -------------
-- 
2.20.1

[PATCH 7/7] docs: Add QEMU version information to HTML footer

[Peter Maydell]

Add a line to the HTML document footer mentioning the QEMU version.
The version information is already provided in very faint text below
the QEMU logo in the sidebar, but that is rather inconspicious, so
repeating it in the footer seems useful.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/_templates/footer.html | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html
index 4c15e17d2a8..977053b5415 100644
--- a/docs/_templates/footer.html
+++ b/docs/_templates/footer.html
@@ -4,6 +4,8 @@
 <!-- Empty para to force a blank line after "Built with Sphinx ..." -->
 <p></p>
 
+<p>This documentation is for QEMU version {{ version }}.</p>
+
 {% trans path=pathto('about/license') %}
 <p><a href="{{ path }}">QEMU and this manual are released under the
 GNU General Public License, version 2.</a></p>
-- 
2.20.1

Re: [PATCH 1/7] docs: Fix documentation Copyright date

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:41AM +0100, Peter Maydell wrote:
> In commit 6d8980a38fa we updated the copyright string we present to
> the user in -version output, About dialogs, etc, but we forgot that
> the Sphinx manuals have a separate copyright string setting.  Update
> that one too.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/conf.py | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 2/7] docs: Stop calling the top level subsections of our manual 'manuals'

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:42AM +0100, Peter Maydell wrote:
> We merged our previous multiple-manual setup into a single Sphinx
> manual, but we left some text in the various index.rst lines that
> still calls the top level subsections separate 'manuals'.  Update
> them to talk about "this section of the manual" instead, and remove
> now-obsolete comments about how the index.rst files are the "top
> level page for the 'foo' manual".
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/devel/index.rst   | 5 +----
>  docs/interop/index.rst | 7 ++-----
>  docs/specs/index.rst   | 5 ++---
>  docs/system/index.rst  | 5 +----
>  docs/tools/index.rst   | 5 ++---
>  docs/user/index.rst    | 5 +----
>  6 files changed, 9 insertions(+), 23 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 4/7] docs: Move deprecation, build and license info out of system/

[Philippe Mathieu-Daudé]

On 7/5/21 11:55 AM, Peter Maydell wrote:
> Now that we have a single Sphinx manual rather than multiple manuals,
> we can provide a better place for "common to all of QEMU" information
> like the deprecation notices, build platforms, license information,
> which we currently have in the system/ manual even though it applies
> to all of QEMU.
> 
> Create a new directory about/ on the same level as system/, user/,
> etc, and move these documents there.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/{system => about}/build-platforms.rst  |  0
>  docs/{system => about}/deprecated.rst       |  0
>  docs/about/index.rst                        | 10 ++++++++++
>  docs/{system => about}/license.rst          |  0
>  docs/{system => about}/removed-features.rst |  0
>  docs/index.rst                              |  1 +
>  docs/system/index.rst                       |  4 ----
>  7 files changed, 11 insertions(+), 4 deletions(-)
>  rename docs/{system => about}/build-platforms.rst (100%)
>  rename docs/{system => about}/deprecated.rst (100%)
>  create mode 100644 docs/about/index.rst
>  rename docs/{system => about}/license.rst (100%)
>  rename docs/{system => about}/removed-features.rst (100%)

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

Re: [PATCH 7/7] docs: Add QEMU version information to HTML footer

[Philippe Mathieu-Daudé]

On 7/5/21 11:55 AM, Peter Maydell wrote:
> Add a line to the HTML document footer mentioning the QEMU version.
> The version information is already provided in very faint text below
> the QEMU logo in the sidebar, but that is rather inconspicious, so
> repeating it in the footer seems useful.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/_templates/footer.html | 2 ++
>  1 file changed, 2 insertions(+)

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

Re: [PATCH 3/7] docs: Remove "Contents:" lines from top-level subsections

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:43AM +0100, Peter Maydell wrote:
> Since the top-level subsections aren't self-contained manuals
> any more, the "Contents:" lines at the top of each of their
> index pages look a bit odd; remove them.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/devel/index.rst   | 2 --
>  docs/interop/index.rst | 2 --
>  docs/specs/index.rst   | 2 --
>  docs/system/index.rst  | 2 --
>  docs/tools/index.rst   | 2 --
>  docs/user/index.rst    | 2 --
>  6 files changed, 12 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 4/7] docs: Move deprecation, build and license info out of system/

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:44AM +0100, Peter Maydell wrote:
> Now that we have a single Sphinx manual rather than multiple manuals,
> we can provide a better place for "common to all of QEMU" information
> like the deprecation notices, build platforms, license information,
> which we currently have in the system/ manual even though it applies
> to all of QEMU.
> 
> Create a new directory about/ on the same level as system/, user/,
> etc, and move these documents there.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/{system => about}/build-platforms.rst  |  0
>  docs/{system => about}/deprecated.rst       |  0
>  docs/about/index.rst                        | 10 ++++++++++
>  docs/{system => about}/license.rst          |  0
>  docs/{system => about}/removed-features.rst |  0
>  docs/index.rst                              |  1 +
>  docs/system/index.rst                       |  4 ----
>  7 files changed, 11 insertions(+), 4 deletions(-)
>  rename docs/{system => about}/build-platforms.rst (100%)
>  rename docs/{system => about}/deprecated.rst (100%)
>  create mode 100644 docs/about/index.rst
>  rename docs/{system => about}/license.rst (100%)
>  rename docs/{system => about}/removed-features.rst (100%)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

This changes hyperlinks for the pages in question, so it is possible
we might have some links to update somewhere.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 5/7] docs: Add some actual About text to about/index.rst

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:45AM +0100, Peter Maydell wrote:
> Add some text to About to act as a brief introduction to the QEMU
> manual and to make the about page a bit less of an abrupt start to
> it.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/about/index.rst | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 6/7] docs: Add license note to the HTML page footer

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:46AM +0100, Peter Maydell wrote:
> The standard Sphinx/RTD HTML page footer gives a copyright line
> (based on the 'copyright' variable set in conf.py) and a line "Built
> with Sphinx using a theme provided by Read the Docs" (which can be
> disabled via the html_show_sphinx variable, but we leave it enabled).
> As a free software project, we'd like to also mention the license
> QEMU and its manual are released under.
> 
> Add a template footer.html which defines the 'extrafooter' block that
> the RtD theme provides for this purpose.  The new line of text will
> go below the existing copyright and sphinx-acknowledgement lines.
> (Unfortunately the RTD footer template does not permit putting it
> after the copyright but before the sphinx-acknowledgement.)
> 
> We use the templating functionality to make the new text also be a
> hyperlink to the about/license.html page of the manual.
> 
> Unlike rst files, HTML template files are not reported to our depfile
> plugin, so we maintain a manual list in meson.build.  New template
> files should be rare, so not being able to auto-generate the
> dependency info is not too awkward.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> I know nothing about Jinja, and have merely cargo-culted the
> "make a link to a document" stuff from the handling of the
> optional copyright link in /usr/share/sphinx_rtd_theme/footer.html ...
> ---
>  docs/_templates/footer.html | 12 ++++++++++++
>  docs/meson.build            |  3 ++-
>  MAINTAINERS                 |  1 +
>  3 files changed, 15 insertions(+), 1 deletion(-)
>  create mode 100644 docs/_templates/footer.html

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 7/7] docs: Add QEMU version information to HTML footer

[Daniel P. Berrangé]

On Mon, Jul 05, 2021 at 10:55:47AM +0100, Peter Maydell wrote:
> Add a line to the HTML document footer mentioning the QEMU version.
> The version information is already provided in very faint text below
> the QEMU logo in the sidebar, but that is rather inconspicious, so
> repeating it in the footer seems useful.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/_templates/footer.html | 2 ++
>  1 file changed, 2 insertions(+)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH 0/7] docs: State QEMU version and license in all HTML footers

[Peter Maydell]

On Mon, 5 Jul 2021 at 10:55, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> This patchset is an effort to fix something up which I promised
> Markus I would do after we got the initial conversion to Sphinx
> done. The old QAPI reference documentation noted the documentation
> license in the texinfo source (but not in the generated HTML or
> in the generated manpages); Sphinx generated docs currently don't.

> I'm open to suggestions on:
>  * name of the new top-level section
>  * text wording
>  * whether we need to have the version number in the footer
>    (it's already in the sidebar under the QEMU logo, but this
>    seemed a bit too inconspicious, so I added it to the footer
>    since I was messing with it anyway)
>
> You can find a built version of the docs at:
> https://pm215.gitlab.io/-/qemu/-/jobs/1399259647/artifacts/public/index.html
>
> I had a look at getting our manpages to also state the license,
> but this is tricky due to various deficiencies in Sphinx.
> (We never have stated the license in our manpages, so this isn't
> a regression compared to the old texinfo setup.)
>
> Markus: do you feel this series is sufficient that we can remove
> the TODO lines in docs/interop/qemu-ga-ref.rst,
> docs/interop/qemu-qmp-ref.rst and docs/interop/qemu-storage-daemon-qmp-ref.rst
> as now being done?

Ping for any further review/opinions, in particular from Markus.
I'm intending to put this in for 6.1.

thanks
-- PMM

Re: [PATCH 0/7] docs: State QEMU version and license in all HTML footers

[Markus Armbruster]

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

> This patchset is an effort to fix something up which I promised
> Markus I would do after we got the initial conversion to Sphinx
> done. The old QAPI reference documentation noted the documentation
> license in the texinfo source (but not in the generated HTML or
> in the generated manpages); Sphinx generated docs currently don't.
>
> The patchset starts with some tidyup that is possible now that
> we have a single combined HTML manual rather than five separate ones.
> Rather than putting common-to-all-QEMU info like the deprecation,
> build and license pages into the "system" manual, we can move them
> out to a new top level section which I have called "About". So that
> the manual doesn't now start too abruptly, I've also added some
> actual "about" text here (mostly cribbed or adapted from our website
> or from other parts of the manual).
>
> Secondly, it uses the Sphinx template-override functionality to
> add more text to the footer added to each HTML page, which will
> now read:
>
> # © Copyright 2021, The QEMU Project Developers.
> #
> # Built with Sphinx using a theme provided by Read the Docs.
> #
> # This documentation is for QEMU version 6.0.50.
> #
> # QEMU and this manual are released under the GNU General Public License, version 2.
>
> where the last line is a hyperlink to the about/license page.
>
> I'm open to suggestions on:
>  * name of the new top-level section

"About" sounds good to me.

>  * text wording

Since Daniel reviewed already, I'd prefer to pass.

>  * whether we need to have the version number in the footer
>    (it's already in the sidebar under the QEMU logo, but this
>    seemed a bit too inconspicious, so I added it to the footer
>    since I was messing with it anyway)

No objection.

> You can find a built version of the docs at:
> https://pm215.gitlab.io/-/qemu/-/jobs/1399259647/artifacts/public/index.html

Lovely improvements overall.

> I had a look at getting our manpages to also state the license,
> but this is tricky due to various deficiencies in Sphinx.
> (We never have stated the license in our manpages, so this isn't
> a regression compared to the old texinfo setup.)

Leaving further improvement for later is okay.

> Markus: do you feel this series is sufficient that we can remove
> the TODO lines in docs/interop/qemu-ga-ref.rst,
> docs/interop/qemu-qmp-ref.rst and docs/interop/qemu-storage-daemon-qmp-ref.rst
> as now being done?

These:

    ..
       TODO: the old Texinfo manual used to note that this manual
       is GPL-v2-or-later. We should make that reader-visible
       both here and in our Sphinx manuals more generally.

    ..
       TODO: display the QEMU version, both here and in our Sphinx manuals
       more generally.

Copyright, license information and version are all visible in the page
footers.  The TODOs can go.

In the old Texinfo manual, copyright and license information was also
visible in the source, like this

    @copying
    This is the QEMU QMP reference manual.
    
    Copyright @copyright{} 2016 The QEMU Project developers
    
    @quotation
    This manual is free documentation: you can redistribute it and/or
    modify it under the terms of the GNU General Public License as
    published by the Free Software Foundation, either version 2 of the
    License, or (at your option) any later version.
    
    This manual is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with this manual.  If not, see http://www.gnu.org/licenses/.
    @end quotation
    @end copying

Such per-file notices are not strictly required, but we habitually have
them in files holding source code.  I'm okay with omitting them in these
.rst files.

However, we got a bunch of .rst files with per-file copyright and
license notices, like this:

    ===================
    Vhost-user Protocol
    ===================
    :Copyright: 2014 Virtual Open Systems Sarl.
    :Copyright: 2019 Intel Corporation
    :Licence: This work is licensed under the terms of the GNU GPL,
              version 2 or later. See the COPYING file in the top-level
              directory.

Rendered to HTML, the page has *two* blocks of copyright and license
information: the above inline, and the footer.  This is confusing.
Worse, the license information is contradictory in places, e.g. with the
above, the inline license is GPLv2 or later, but the footer is GPLv2
exactly.  I know the intent (footer applies to QEMU as a whole, inline
just to this page), but legalese should be as clear as we can make it.

Can we downgrade the inline notices to comments?

This is a separate issue we can address on top for 6.1, so:
Acked-by: Markus Armbruster <armbru@redhat.com>