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