[PATCH for-5.0 0/8] docs: integrate doc comments with Sphinx build

Paolo Bonzini posted 8 patches 31 weeks ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20191129140217.17797-1-pbonzini@redhat.com
Test FreeBSD passed
Test checkpatch failed
Test docker-clang@ubuntu passed
Test docker-mingw@fedora passed
Test docker-quick@centos7 passed
Test asan passed
Maintainers: Peter Maydell <peter.maydell@linaro.org>, Paolo Bonzini <pbonzini@redhat.com>
Makefile                 |    2 +-
docs/conf.py             |    7 +-
docs/devel/bitops.rst    |    8 +
docs/devel/index.rst     |    1 +
docs/devel/memory.rst    |    5 +
docs/sphinx/kerneldoc.py |  172 +++
docs/sphinx/kernellog.py |   28 +
include/exec/memory.h    |   16 +-
include/qemu/bitops.h    |   52 +-
scripts/kernel-doc       | 2236 ++++++++++++++++++++++++++++++++++++++
10 files changed, 2499 insertions(+), 28 deletions(-)
create mode 100644 docs/devel/bitops.rst
create mode 100644 docs/sphinx/kerneldoc.py
create mode 100644 docs/sphinx/kernellog.py
create mode 100755 scripts/kernel-doc

[PATCH for-5.0 0/8] docs: integrate doc comments with Sphinx build

Posted by Paolo Bonzini 31 weeks ago
This merges my series and Peter's into one.  Both the memory API and bitwise
operation APIs are covered.

Paolo Bonzini (4):
  docs: import Linux kernel-doc script and extension
  docs: tweak kernel-doc for QEMU coding standards
  memory.h: Silence kernel-doc complaints
  docs: add memory API reference

Peter Maydell (4):
  docs/conf.py: Enable use of kerneldoc sphinx extension
  Makefile: disable Sphinx nitpicking
  bitops.h: Silence kernel-doc complaints
  docs: Create bitops.rst as example of kernel-docs

 Makefile                 |    2 +-
 docs/conf.py             |    7 +-
 docs/devel/bitops.rst    |    8 +
 docs/devel/index.rst     |    1 +
 docs/devel/memory.rst    |    5 +
 docs/sphinx/kerneldoc.py |  172 +++
 docs/sphinx/kernellog.py |   28 +
 include/exec/memory.h    |   16 +-
 include/qemu/bitops.h    |   52 +-
 scripts/kernel-doc       | 2236 ++++++++++++++++++++++++++++++++++++++
 10 files changed, 2499 insertions(+), 28 deletions(-)
 create mode 100644 docs/devel/bitops.rst
 create mode 100644 docs/sphinx/kerneldoc.py
 create mode 100644 docs/sphinx/kernellog.py
 create mode 100755 scripts/kernel-doc

-- 
2.21.0


Re: [PATCH for-5.0 0/8] docs: integrate doc comments with Sphinx build

Posted by Peter Maydell 31 weeks ago
On Fri, 29 Nov 2019 at 14:02, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> This merges my series and Peter's into one.  Both the memory API and bitwise
> operation APIs are covered.
>
> Paolo Bonzini (4):
>   docs: import Linux kernel-doc script and extension
>   docs: tweak kernel-doc for QEMU coding standards
>   memory.h: Silence kernel-doc complaints
>   docs: add memory API reference
>
> Peter Maydell (4):
>   docs/conf.py: Enable use of kerneldoc sphinx extension
>   Makefile: disable Sphinx nitpicking
>   bitops.h: Silence kernel-doc complaints
>   docs: Create bitops.rst as example of kernel-docs

Thanks for folding those two series together; I've left
review comments on the parts I didn't write.

Do you have a URL of a rendered version of the docs
somewhere handy to save me applying the series locally ?

thanks
-- PMM

Re: [PATCH for-5.0 0/8] docs: integrate doc comments with Sphinx build

Posted by Paolo Bonzini 31 weeks ago
On 02/12/19 19:06, Peter Maydell wrote:
> On Fri, 29 Nov 2019 at 14:02, Paolo Bonzini <pbonzini@redhat.com> wrote:
>>
>> This merges my series and Peter's into one.  Both the memory API and bitwise
>> operation APIs are covered.
>>
>> Paolo Bonzini (4):
>>   docs: import Linux kernel-doc script and extension
>>   docs: tweak kernel-doc for QEMU coding standards
>>   memory.h: Silence kernel-doc complaints
>>   docs: add memory API reference
>>
>> Peter Maydell (4):
>>   docs/conf.py: Enable use of kerneldoc sphinx extension
>>   Makefile: disable Sphinx nitpicking
>>   bitops.h: Silence kernel-doc complaints
>>   docs: Create bitops.rst as example of kernel-docs
> 
> Thanks for folding those two series together; I've left
> review comments on the parts I didn't write.
> 
> Do you have a URL of a rendered version of the docs
> somewhere handy to save me applying the series locally ?

No, I don't.

Paolo


Re: [PATCH for-5.0 0/8] docs: integrate doc comments with Sphinx build

Posted by no-reply@patchew.org 31 weeks ago
Patchew URL: https://patchew.org/QEMU/20191129140217.17797-1-pbonzini@redhat.com/



Hi,

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

Subject: [PATCH for-5.0 0/8] docs: integrate doc comments with Sphinx build
Type: series
Message-id: 20191129140217.17797-1-pbonzini@redhat.com

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

Switched to a new branch 'test'
b3ce185 docs: add memory API reference
de50eba memory.h: Silence kernel-doc complaints
0f0cc93 docs: Create bitops.rst as example of kernel-docs
7de419c bitops.h: Silence kernel-doc complaints
0ac6a81 Makefile: disable Sphinx nitpicking
0b3c7c9 docs/conf.py: Enable use of kerneldoc sphinx extension
10457ca docs: tweak kernel-doc for QEMU coding standards
f7a1036 docs: import Linux kernel-doc script and extension

=== OUTPUT BEGIN ===
1/8 Checking commit f7a103632856 (docs: import Linux kernel-doc script and extension)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#20: 
new file mode 100644

WARNING: line over 80 characters
#102: FILE: docs/sphinx/kerneldoc.py:78:
+        tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)

WARNING: line over 80 characters
#132: FILE: docs/sphinx/kerneldoc.py:108:
+            p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

ERROR: line over 90 characters
#141: FILE: docs/sphinx/kerneldoc.py:117:
+                               'kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))

WARNING: line over 80 characters
#142: FILE: docs/sphinx/kerneldoc.py:118:
+                return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]

WARNING: line over 80 characters
#146: FILE: docs/sphinx/kerneldoc.py:122:
+            lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)

WARNING: line over 80 characters
#167: FILE: docs/sphinx/kerneldoc.py:143:
+            kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed with: %s' %

WARNING: line over 80 characters
#169: FILE: docs/sphinx/kerneldoc.py:145:
+            return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]

ERROR: line over 90 characters
#176: FILE: docs/sphinx/kerneldoc.py:152:
+            save = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter

WARNING: line over 80 characters
#177: FILE: docs/sphinx/kerneldoc.py:153:
+            self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)

ERROR: line over 90 characters
#182: FILE: docs/sphinx/kerneldoc.py:158:
+                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = save

total: 3 errors, 8 warnings, 2426 lines checked

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

2/8 Checking commit 10457ca7be94 (docs: tweak kernel-doc for QEMU coding standards)
3/8 Checking commit 0b3c7c9f8788 (docs/conf.py: Enable use of kerneldoc sphinx extension)
4/8 Checking commit 0ac6a8162879 (Makefile: disable Sphinx nitpicking)
5/8 Checking commit 7de419c91dc7 (bitops.h: Silence kernel-doc complaints)
6/8 Checking commit 0f0cc9310e25 (docs: Create bitops.rst as example of kernel-docs)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#18: 
new file mode 100644

total: 0 errors, 1 warnings, 12 lines checked

Patch 6/8 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
7/8 Checking commit de50ebaf7d96 (memory.h: Silence kernel-doc complaints)
WARNING: Block comments use a leading /* on a separate line
#21: FILE: include/exec/memory.h:363:
+/** MemoryRegion:

total: 0 errors, 1 warnings, 43 lines checked

Patch 7/8 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
8/8 Checking commit b3ce1857d7cb (docs: add memory API reference)
=== OUTPUT END ===

Test command exited with code: 1


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