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

Paolo Bonzini posted 8 patches 4 years, 3 months 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 4 years, 3 months 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 4 years, 3 months 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 4 years, 3 months 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 4 years, 3 months 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