[v2] Enable build and install of our rST docs

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

Posted by Peter Maydell 6 years, 7 months ago

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

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

All patches except 9 have been reviewed.

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


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


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

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

To see the results:

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

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

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

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

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


thanks
-- PMM


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

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

-- 
2.20.1

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

Posted by no-reply@patchew.org 6 years, 7 months ago

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



Hi,

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

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

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

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

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

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

Test command exited with code: 1


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

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

Posted by no-reply@patchew.org 6 years, 7 months ago

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



Hi,

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

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

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

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

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

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

Test command exited with code: 1


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

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

Posted by no-reply@patchew.org 6 years, 7 months ago

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



Hi,

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

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

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

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

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

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

Test command exited with code: 1


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

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

Posted by no-reply@patchew.org 6 years, 7 months ago

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



Hi,

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

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

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

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

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

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

Test command exited with code: 1


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

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

Posted by no-reply@patchew.org 6 years, 7 months ago

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



Hi,

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

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

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

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

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

total: 0 errors, 1 warnings, 195 lines checked

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

total: 0 errors, 1 warnings, 188 lines checked

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

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

total: 1 errors, 1 warnings, 133 lines checked

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

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

Test command exited with code: 1


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

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

Posted by Aleksandar Markovic 6 years, 7 months ago

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

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

For the entire series:

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

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