* [PULL] Docs for 4.13
@ 2017-07-03 13:20 Jonathan Corbet
2017-07-04 4:32 ` Linus Torvalds
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2017-07-03 13:20 UTC (permalink / raw)
To: Linus Torvalds; +Cc: LKML, linux-doc
The following changes since commit
2ea659a9ef488125eb46da6eb571de5eae5c43f6:
Linux 4.12-rc1 (2017-05-13 13:19:49 -0700)
are available in the git repository at:
git://git.lwn.net/linux.git tags/docs-4.13
for you to fetch changes up to 1cb566ba5634d7593b8b2a0a5c83f1c9e14b2e09:
scripts/kernel-doc: handle DECLARE_HASHTABLE (2017-07-03 06:57:09 -0600)
----------------------------------------------------------------
There has been a fair amount of activity in the docs tree this time
around. Highlights include:
- Conversion of a bunch of security documentation into RST
- The conversion of the remaining DocBook templates by The Amazing
Mauro Machine. We can now drop the entire DocBook build chain.
- The usual collection of fixes and minor updates.
NOTES: this is a somewhat messy-looking pull, unfortunately, due to the
nature of the changes. Mauro's work, in particular, involved fixing
lots of kerneldoc comments elsewhere in the tree; there are no code
changes in the non-docs stuff.
You'll also encounter more than the usual number of conflicts, which
is saying something. The tip tree tweaked kernel-hacking.tmpl,
which got converted to RST; the change just needs to be carried
over. There is a similar situation with w1.tmpl being changed in
the char-misc tree. Kbuild wants to change the shebang line in the
kernel-doc-xml-ref tool, but that tool is just not needed anymore.
Hopefully, as the transition settles down we'll see less of this
kind of stuff. Meanwhile thanks to Stephen for flagging and
managing all of these.
----------------------------------------------------------------
Ayan Shafqat (1):
Doc: fix a markup error in coding-style.rst
Jakub Kicinski (1):
scripts/kernel-doc: handle DECLARE_HASHTABLE
Jonathan Corbet (7):
Merge tag 'v4.12-rc1' into docs-next
docs: Fix some formatting issues in request-key.rst
Merge remote-tracking branch 'mauro-exp/docbook3' into death-to-docbook
Docs: Include the Latex "ifthen" package
Docs: fix table problems in ras.rst
Docs: Use kernel-figure in vidioc-g-selection.rst
Docs: clean up some DocBook loose ends
Kees Cook (17):
doc: ReSTify seccomp_filter.txt
doc: ReSTify no_new_privs.txt
doc: ReSTify IMA-templates.txt
doc: ReSTify credentials.txt
doc: ReSTify self-protection.txt
doc: security: minor cleanups to build kernel-doc
doc: ReSTify and split LSM.txt
doc: ReSTify SELinux.txt
doc: ReSTify apparmor.txt
doc: ReSTify tomoyo.txt
doc: ReSTify Yama.txt
doc: ReSTify LoadPin.txt
doc: ReSTify Smack.txt
doc: ReSTify keys.txt
doc: ReSTify keys-ecryptfs.txt
doc: ReSTify keys-request-key.txt
doc: ReSTify keys-trusted-encrypted.txt
Konstantin Ryabitsev (1):
Make the main documentation title less Geocities
Markus Heiser (2):
core-api: remove an unexpected unident
doc-rst: fix inline emphasis in unshare.rst
Mauro Carvalho Chehab (54):
docs-rst: convert kernel-hacking to ReST
kernel-hacking: update document
docs-rst: convert kernel-locking to ReST
mutex, futex: adjust kernel-doc markups to generate ReST
locking.rst: reformat locking table
locking.rst: add captions to two tables
locking.rst: Update some ReST markups
docs-rst: convert kgdb DocBook to ReST
kgdb.rst: Adjust ReST markups
conf.py: define a color for important markup on PDF output
docs-rst: conf.py: sort LaTeX documents in alphabetical order
docs-rst: conf.py: remove kernel-documentation from LaTeX
docs-rst: add crypto API book to pdf output
docs-rst: add dev-tools book to pdf output
docs-rst: add sound book to pdf output
docs-rst: add userspace API book to pdf output
docs-rst: convert filesystems book to ReST
docs-rst: filesystems: use c domain references where needed
fs: jbd2: make jbd2_journal_start() kernel-doc parseable
docs-rst: don't ignore internal functions for jbd2 docs
fs: add a blank lines on some kernel-doc comments
fs: eventfd: fix identation on kernel-doc
fs: jbd2: escape a string with special chars on a kernel-doc
docs-rst: convert libata book to ReST
libata.rst: add c function and struct cross-references
libata: fix identation on a kernel-doc markup
docs-rst: convert s390-drivers DocBook to ReST
docs-rst: convert networking book to ReST
net: skbuff.h: properly escape a macro name on kernel-doc
net: fix some identation issues at kernel-doc markups
docs-rst: convert z8530book DocBook to ReST
docs-rst: convert scsi DocBook to ReST
scsi: fix some kernel-doc markups
docs-rst: convert w1 book to ReST
docs-rst: convert rapidio book to ReST
docs-rst: convert librs book to ReST
docs-rst: convert mtdnand book to ReST
mtdnand.rst: group the "::" with previous line
mtd: adjust kernel-docs to avoid Sphinx/kerneldoc warnings
docs-rst: convert sh book to ReST
docs-rst: convert lsm from DocBook to ReST
docs: remove DocBook from the building system
docs: update old references for DocBook from the documentation
MAINTAINERS: update old references for DocBook directory
ata: update references for libata documentation
ia64, scsi: update references for the device-io book
irq: update genericirq book location
fs: update location of filesystems documentation
lib: update location of kgdb documentation
fs: fix the location of the kernel-api book
usb: fix the comment with regards to DocBook
docs-rst: get rid of Documentation/sphinx/tmplcvt script
kernel-doc: describe the ``literal`` syntax
Docs: Fix breakage with Sphinx 1.5 and upper
Palmer Dabbelt (1):
Documentation: atomic_ops.txt is core-api/atomic_ops.rst
Sanjeev Gupta (1):
Docs: Insert missing space to separate link from text
SeongJae Park (2):
doc/ko_KR/memory-barriers: Update control-dependencies example
doc/kokr/howto: Only send regression fixes after -rc1
Steffen Maier (1):
docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters
Stewart Smith (1):
doc: Document suitability of IBM Verse for kernel development
Tobias Klauser (1):
Documentation, kbuild: fix typo "minimun" -> "minimum"
Wolfram Sang (2):
Documentation: DMA API: fix a typo in a function name
docs: driver-api: i2c: remove some outdated information
Documentation/00-INDEX | 6 +-
Documentation/DMA-API.txt | 2 +-
Documentation/DocBook/.gitignore | 17 -
Documentation/DocBook/Makefile | 282 ---
Documentation/DocBook/filesystems.tmpl | 381 ----
Documentation/DocBook/kernel-hacking.tmpl | 1312 ------------
Documentation/DocBook/kernel-locking.tmpl | 2151 --------------------
Documentation/DocBook/kgdb.tmpl | 918 ---------
Documentation/DocBook/libata.tmpl | 1625 ---------------
Documentation/DocBook/librs.tmpl | 289 ---
Documentation/DocBook/lsm.tmpl | 265 ---
Documentation/DocBook/mtdnand.tmpl | 1291 ------------
Documentation/DocBook/networking.tmpl | 111 -
Documentation/DocBook/rapidio.tmpl | 155 --
Documentation/DocBook/s390-drivers.tmpl | 161 --
Documentation/DocBook/scsi.tmpl | 409 ----
Documentation/DocBook/sh.tmpl | 105 -
Documentation/DocBook/stylesheet.xsl | 11 -
Documentation/DocBook/w1.tmpl | 101 -
Documentation/DocBook/z8530book.tmpl | 371 ----
Documentation/Makefile | 125 ++
Documentation/Makefile.sphinx | 130 --
Documentation/PCI/MSI-HOWTO.txt | 2 +-
.../LoadPin.txt => admin-guide/LSM/LoadPin.rst} | 12 +-
.../SELinux.txt => admin-guide/LSM/SELinux.rst} | 18 +-
.../Smack.txt => admin-guide/LSM/Smack.rst} | 273 ++-
.../Yama.txt => admin-guide/LSM/Yama.rst} | 55 +-
.../apparmor.txt => admin-guide/LSM/apparmor.rst} | 36 +-
.../LSM.txt => admin-guide/LSM/index.rst} | 28 +-
.../tomoyo.txt => admin-guide/LSM/tomoyo.rst} | 22 +-
Documentation/admin-guide/README.rst | 6 -
Documentation/admin-guide/index.rst | 1 +
Documentation/admin-guide/kernel-parameters.txt | 6 +-
Documentation/admin-guide/ras.rst | 10 +-
Documentation/conf.py | 44 +-
Documentation/core-api/assoc_array.rst | 5 +-
Documentation/core-api/index.rst | 1 +
Documentation/core-api/librs.rst | 212 ++
Documentation/crypto/asymmetric-keys.txt | 2 +-
Documentation/crypto/conf.py | 10 +
Documentation/dev-tools/index.rst | 1 +
Documentation/dev-tools/kgdb.rst | 907 +++++++++
Documentation/doc-guide/docbook.rst | 90 -
Documentation/doc-guide/index.rst | 1 -
Documentation/doc-guide/kernel-doc.rst | 10 +
Documentation/doc-guide/sphinx.rst | 5 -
Documentation/dontdiff | 1 -
Documentation/driver-api/i2c.rst | 9 +-
Documentation/driver-api/index.rst | 6 +
Documentation/driver-api/libata.rst | 1031 ++++++++++
Documentation/driver-api/mtdnand.rst | 1007 +++++++++
Documentation/driver-api/rapidio.rst | 107 +
Documentation/driver-api/s390-drivers.rst | 111 +
Documentation/driver-api/scsi.rst | 344 ++++
Documentation/driver-api/w1.rst | 70 +
Documentation/fb/api.txt | 4 +-
Documentation/filesystems/conf.py | 10 +
Documentation/filesystems/index.rst | 317 +++
Documentation/filesystems/nfs/idmapper.txt | 2 +-
Documentation/gpu/todo.rst | 2 +-
Documentation/index.rst | 18 +-
Documentation/kbuild/makefiles.txt | 2 +-
Documentation/kernel-doc-nano-HOWTO.txt | 65 +-
Documentation/kernel-hacking/conf.py | 10 +
Documentation/kernel-hacking/hacking.rst | 811 ++++++++
Documentation/kernel-hacking/index.rst | 9 +
Documentation/kernel-hacking/locking.rst | 1446 +++++++++++++
Documentation/lsm.txt | 201 ++
.../media/uapi/v4l/vidioc-g-selection.rst | 4 +-
Documentation/memory-barriers.txt | 10 +-
Documentation/networking/conf.py | 10 +
Documentation/networking/dns_resolver.txt | 2 +-
Documentation/networking/index.rst | 18 +
Documentation/networking/kapi.rst | 147 ++
Documentation/networking/z8530book.rst | 256 +++
Documentation/process/changes.rst | 26 +-
Documentation/process/coding-style.rst | 4 +-
Documentation/process/email-clients.rst | 5 +
Documentation/process/howto.rst | 8 -
Documentation/process/kernel-docs.rst | 34 +-
Documentation/security/00-INDEX | 26 -
.../{IMA-templates.txt => IMA-templates.rst} | 46 +-
Documentation/security/LSM.rst | 14 +
Documentation/security/conf.py | 8 -
.../security/{credentials.txt => credentials.rst} | 275 ++-
Documentation/security/index.rst | 8 +-
Documentation/security/{keys.txt => keys/core.rst} | 314 ++-
.../{keys-ecryptfs.txt => keys/ecryptfs.rst} | 19 +-
Documentation/security/keys/index.rst | 11 +
.../{keys-request-key.txt => keys/request-key.rst} | 73 +-
.../trusted-encrypted.rst} | 32 +-
.../{self-protection.txt => self-protection.rst} | 99 +-
Documentation/sh/conf.py | 10 +
Documentation/sh/index.rst | 59 +
Documentation/sound/conf.py | 10 +
Documentation/sphinx/convert_template.sed | 18 -
Documentation/sphinx/post_convert.sed | 23 -
Documentation/sphinx/tmplcvt | 28 -
Documentation/translations/ja_JP/howto.rst | 7 -
Documentation/translations/ko_KR/howto.rst | 27 +-
.../translations/ko_KR/memory-barriers.txt | 2 +-
Documentation/userspace-api/index.rst | 2 +
.../no_new_privs.rst} | 44 +-
.../seccomp_filter.rst} | 116 +-
Documentation/userspace-api/unshare.rst | 2 +-
MAINTAINERS | 21 +-
Makefile | 10 +-
arch/ia64/include/asm/io.h | 2 +-
arch/ia64/sn/kernel/iomv.c | 2 +-
drivers/ata/acard-ahci.c | 2 +-
drivers/ata/ahci.c | 2 +-
drivers/ata/ahci.h | 2 +-
drivers/ata/ata_piix.c | 2 +-
drivers/ata/libahci.c | 2 +-
drivers/ata/libata-core.c | 2 +-
drivers/ata/libata-eh.c | 2 +-
drivers/ata/libata-scsi.c | 9 +-
drivers/ata/libata-sff.c | 2 +-
drivers/ata/libata.h | 2 +-
drivers/ata/pata_pdc2027x.c | 2 +-
drivers/ata/pdc_adma.c | 2 +-
drivers/ata/sata_nv.c | 2 +-
drivers/ata/sata_promise.c | 2 +-
drivers/ata/sata_promise.h | 2 +-
drivers/ata/sata_qstor.c | 2 +-
drivers/ata/sata_sil.c | 2 +-
drivers/ata/sata_sis.c | 2 +-
drivers/ata/sata_svw.c | 2 +-
drivers/ata/sata_sx4.c | 2 +-
drivers/ata/sata_uli.c | 2 +-
drivers/ata/sata_via.c | 2 +-
drivers/ata/sata_vsc.c | 2 +-
drivers/mtd/nand/nand_base.c | 7 +-
drivers/net/phy/phy.c | 1 +
drivers/scsi/qla1280.c | 2 +-
drivers/scsi/scsi_scan.c | 7 +-
drivers/scsi/scsi_transport_fc.c | 18 +-
drivers/scsi/scsicam.c | 4 +-
drivers/usb/gadget/Kconfig | 2 +-
fs/debugfs/file.c | 2 +-
fs/debugfs/inode.c | 2 +-
fs/eventfd.c | 4 +-
fs/fs-writeback.c | 12 +-
fs/jbd2/transaction.c | 42 +-
fs/mpage.c | 1 +
fs/namei.c | 1 +
include/linux/ata.h | 2 +-
include/linux/cred.h | 2 +-
include/linux/debugfs.h | 2 +-
include/linux/key.h | 2 +-
include/linux/libata.h | 2 +-
include/linux/lsm_hooks.h | 25 +-
include/linux/mtd/nand.h | 2 +-
include/linux/mutex.h | 6 +-
include/linux/netdevice.h | 9 +-
include/linux/skbuff.h | 2 +-
include/net/sock.h | 9 +-
kernel/cred.c | 2 +-
kernel/futex.c | 40 +-
kernel/irq/chip.c | 2 +-
kernel/irq/handle.c | 2 +-
kernel/irq/irqdesc.c | 2 +-
kernel/locking/mutex.c | 6 +-
lib/Kconfig.debug | 2 +-
lib/Kconfig.kgdb | 2 +-
net/core/datagram.c | 2 +-
net/core/sock.c | 7 +-
scripts/.gitignore | 1 -
scripts/Makefile | 10 +-
scripts/check-lc_ctype.c | 11 -
scripts/docproc.c | 681 -------
scripts/kernel-doc | 2 +
scripts/kernel-doc-xml-ref | 198 --
scripts/selinux/README | 2 +-
security/apparmor/match.c | 2 +-
security/apparmor/policy_unpack.c | 2 +-
security/keys/encrypted-keys/encrypted.c | 2 +-
security/keys/encrypted-keys/masterkey_trusted.c | 2 +-
security/keys/request_key.c | 2 +-
security/keys/request_key_auth.c | 2 +-
security/keys/trusted.c | 2 +-
security/yama/Kconfig | 3 +-
182 files changed, 8404 insertions(+), 12196 deletions(-)
delete mode 100644 Documentation/DocBook/.gitignore
delete mode 100644 Documentation/DocBook/Makefile
delete mode 100644 Documentation/DocBook/filesystems.tmpl
delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl
delete mode 100644 Documentation/DocBook/kernel-locking.tmpl
delete mode 100644 Documentation/DocBook/kgdb.tmpl
delete mode 100644 Documentation/DocBook/libata.tmpl
delete mode 100644 Documentation/DocBook/librs.tmpl
delete mode 100644 Documentation/DocBook/lsm.tmpl
delete mode 100644 Documentation/DocBook/mtdnand.tmpl
delete mode 100644 Documentation/DocBook/networking.tmpl
delete mode 100644 Documentation/DocBook/rapidio.tmpl
delete mode 100644 Documentation/DocBook/s390-drivers.tmpl
delete mode 100644 Documentation/DocBook/scsi.tmpl
delete mode 100644 Documentation/DocBook/sh.tmpl
delete mode 100644 Documentation/DocBook/stylesheet.xsl
delete mode 100644 Documentation/DocBook/w1.tmpl
delete mode 100644 Documentation/DocBook/z8530book.tmpl
delete mode 100644 Documentation/Makefile.sphinx
rename Documentation/{security/LoadPin.txt => admin-guide/LSM/LoadPin.rst} (73%)
rename Documentation/{security/SELinux.txt => admin-guide/LSM/SELinux.rst} (71%)
rename Documentation/{security/Smack.txt => admin-guide/LSM/Smack.rst} (85%)
rename Documentation/{security/Yama.txt => admin-guide/LSM/Yama.rst} (60%)
rename Documentation/{security/apparmor.txt => admin-guide/LSM/apparmor.rst} (65%)
rename Documentation/{security/LSM.txt => admin-guide/LSM/index.rst} (62%)
rename Documentation/{security/tomoyo.txt => admin-guide/LSM/tomoyo.rst} (85%)
create mode 100644 Documentation/core-api/librs.rst
create mode 100644 Documentation/crypto/conf.py
create mode 100644 Documentation/dev-tools/kgdb.rst
delete mode 100644 Documentation/doc-guide/docbook.rst
create mode 100644 Documentation/driver-api/libata.rst
create mode 100644 Documentation/driver-api/mtdnand.rst
create mode 100644 Documentation/driver-api/rapidio.rst
create mode 100644 Documentation/driver-api/s390-drivers.rst
create mode 100644 Documentation/driver-api/scsi.rst
create mode 100644 Documentation/driver-api/w1.rst
create mode 100644 Documentation/filesystems/conf.py
create mode 100644 Documentation/filesystems/index.rst
create mode 100644 Documentation/kernel-hacking/conf.py
create mode 100644 Documentation/kernel-hacking/hacking.rst
create mode 100644 Documentation/kernel-hacking/index.rst
create mode 100644 Documentation/kernel-hacking/locking.rst
create mode 100644 Documentation/lsm.txt
create mode 100644 Documentation/networking/conf.py
create mode 100644 Documentation/networking/index.rst
create mode 100644 Documentation/networking/kapi.rst
create mode 100644 Documentation/networking/z8530book.rst
delete mode 100644 Documentation/security/00-INDEX
rename Documentation/security/{IMA-templates.txt => IMA-templates.rst} (72%)
create mode 100644 Documentation/security/LSM.rst
delete mode 100644 Documentation/security/conf.py
rename Documentation/security/{credentials.txt => credentials.rst} (72%)
rename Documentation/security/{keys.txt => keys/core.rst} (89%)
rename Documentation/security/{keys-ecryptfs.txt => keys/ecryptfs.rst} (91%)
create mode 100644 Documentation/security/keys/index.rst
rename Documentation/security/{keys-request-key.txt => keys/request-key.rst} (77%)
rename Documentation/security/{keys-trusted-encrypted.txt => keys/trusted-encrypted.rst} (93%)
rename Documentation/security/{self-protection.txt => self-protection.rst} (83%)
create mode 100644 Documentation/sh/conf.py
create mode 100644 Documentation/sh/index.rst
create mode 100644 Documentation/sound/conf.py
delete mode 100644 Documentation/sphinx/convert_template.sed
delete mode 100644 Documentation/sphinx/post_convert.sed
delete mode 100755 Documentation/sphinx/tmplcvt
rename Documentation/{prctl/no_new_privs.txt => userspace-api/no_new_privs.rst} (54%)
rename Documentation/{prctl/seccomp_filter.txt => userspace-api/seccomp_filter.rst} (71%)
delete mode 100644 scripts/check-lc_ctype.c
delete mode 100644 scripts/docproc.c
delete mode 100755 scripts/kernel-doc-xml-ref
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PULL] Docs for 4.13
2017-07-03 13:20 [PULL] Docs for 4.13 Jonathan Corbet
@ 2017-07-04 4:32 ` Linus Torvalds
2017-07-04 7:56 ` Markus Heiser
2017-07-04 19:24 ` Jonathan Corbet
0 siblings, 2 replies; 5+ messages in thread
From: Linus Torvalds @ 2017-07-04 4:32 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: LKML, open list:DOCUMENTATION
On Mon, Jul 3, 2017 at 6:20 AM, Jonathan Corbet <corbet@lwn.net> wrote:
> You'll also encounter more than the usual number of conflicts, which
> is saying something.
Hmm. I fixed the ones that were actual data conflicts, but I think
there ends up being several things that are just stale or didn't get
updated by other pulls.
Eg things like
Error: Cannot open file ./kernel/rcu/srcu.c
Error: Cannot open file ./kernel/rcu/srcu.c
happen simply because that file no longer exists, and the docs never
got updated.
So my merge didn't even try to fix those kinds of things at all. I
literally just looked at the conflicts and moved those over to the rst
files, and that was it. There's a lot of other changes that never
cause conflicts for the simple reason that those changes never caused
documentation changes to begin with.
Now, this is obviously not new, but it does strike me that if checking
for these kinds of things was easier and part of "make allmodconfig",
then we might have less of it happen.
At the same time, lots of people run a lot of builds, and while I'd
love to see warnings about docs failures, I am *not* willing to slow
down my usual build enormously. I run "male allmodconfig" builds
between every single pull during the merge window, and while it's
often parallel with me looking at the problems, I don't really want to
slow the build down too much. And the doc building is still *slow*.
Is there some fast "just basic sanity checks" that would be more reasonable?
Because one thing that the switch to sphinx has done is that the doc
build environment seems saner (tool-wise). So now that kind of thing
would at least be _possible_ to do in ways I don't think was
reasonable with docbook.
And now docbook is finally gone. But sphinx isn't exactly a speed demon either.
Linus
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PULL] Docs for 4.13
2017-07-04 4:32 ` Linus Torvalds
@ 2017-07-04 7:56 ` Markus Heiser
2017-07-04 19:24 ` Jonathan Corbet
1 sibling, 0 replies; 5+ messages in thread
From: Markus Heiser @ 2017-07-04 7:56 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: LKML, Linux Doc Mailing List, Linus Torvalds
Hi Jon,
> Am 04.07.2017 um 06:32 schrieb Linus Torvalds <torvalds@linux-foundation.org>:
[...]
> At the same time, lots of people run a lot of builds, and while I'd
> love to see warnings about docs failures, I am *not* willing to slow
> down my usual build enormously. I run "male allmodconfig" builds
> between every single pull during the merge window, and while it's
> often parallel with me looking at the problems, I don't really want to
> slow the build down too much. And the doc building is still *slow*.
>
> Is there some fast "just basic sanity checks" that would be more reasonable?
>
> Because one thing that the switch to sphinx has done is that the doc
> build environment seems saner (tool-wise). So now that kind of thing
> would at least be _possible_ to do in ways I don't think was
> reasonable with docbook.
Sphinx has 'dummy' builder since v1.4. I send a patch with a lintdocs
target [1]. Having a lintdocs target under which we can optimizes
linting might be useful at all and the 'dummy' builder is IMO a
good starting point ..
> And now docbook is finally gone. But sphinx isn't exactly a speed demon either.
The time-saving of the 'dummy' builder against the 'html' builder is about 40%.
[1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg13248.html
-- Markus --
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PULL] Docs for 4.13
2017-07-04 4:32 ` Linus Torvalds
2017-07-04 7:56 ` Markus Heiser
@ 2017-07-04 19:24 ` Jonathan Corbet
2017-07-15 9:04 ` Daniel Vetter
1 sibling, 1 reply; 5+ messages in thread
From: Jonathan Corbet @ 2017-07-04 19:24 UTC (permalink / raw)
To: Linus Torvalds; +Cc: LKML, open list:DOCUMENTATION
On Mon, 3 Jul 2017 21:32:33 -0700
Linus Torvalds <torvalds@linux-foundation.org> wrote:
> Eg things like
>
> Error: Cannot open file ./kernel/rcu/srcu.c
> Error: Cannot open file ./kernel/rcu/srcu.c
>
> happen simply because that file no longer exists, and the docs never
> got updated.
>
> So my merge didn't even try to fix those kinds of things at all. I
> literally just looked at the conflicts and moved those over to the rst
> files, and that was it. There's a lot of other changes that never
> cause conflicts for the simple reason that those changes never caused
> documentation changes to begin with.
>
> Now, this is obviously not new, but it does strike me that if checking
> for these kinds of things was easier and part of "make allmodconfig",
> then we might have less of it happen.
I see Markus already tossed out a patch using the sphinx "dummy mode".
It might be possible to create a dead-simple linter for this kind of
thing that would be quite a bit faster, but I wonder how much we really
need it. Problems like this pop up with great regularity, but they
tend to be caught and fixed fairly quickly. Meanwhile, the world
stubbornly refuses to end if the docs build tosses out a few (more)
errors for a few days. I don't think we have to slow down everybody's
build for this.
(Getting something into the build-and-boot testers might not be a bad
idea, though).
I've committed a patch to fix this particular problem, will send it
youward in a few days.
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PULL] Docs for 4.13
2017-07-04 19:24 ` Jonathan Corbet
@ 2017-07-15 9:04 ` Daniel Vetter
0 siblings, 0 replies; 5+ messages in thread
From: Daniel Vetter @ 2017-07-15 9:04 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linus Torvalds, LKML, open list:DOCUMENTATION
On Tue, Jul 04, 2017 at 01:24:13PM -0600, Jonathan Corbet wrote:
> On Mon, 3 Jul 2017 21:32:33 -0700
> Linus Torvalds <torvalds@linux-foundation.org> wrote:
>
> > Eg things like
> >
> > Error: Cannot open file ./kernel/rcu/srcu.c
> > Error: Cannot open file ./kernel/rcu/srcu.c
> >
> > happen simply because that file no longer exists, and the docs never
> > got updated.
> >
> > So my merge didn't even try to fix those kinds of things at all. I
> > literally just looked at the conflicts and moved those over to the rst
> > files, and that was it. There's a lot of other changes that never
> > cause conflicts for the simple reason that those changes never caused
> > documentation changes to begin with.
> >
> > Now, this is obviously not new, but it does strike me that if checking
> > for these kinds of things was easier and part of "make allmodconfig",
> > then we might have less of it happen.
>
> I see Markus already tossed out a patch using the sphinx "dummy mode".
> It might be possible to create a dead-simple linter for this kind of
> thing that would be quite a bit faster, but I wonder how much we really
> need it. Problems like this pop up with great regularity, but they
> tend to be caught and fixed fairly quickly. Meanwhile, the world
> stubbornly refuses to end if the docs build tosses out a few (more)
> errors for a few days. I don't think we have to slow down everybody's
> build for this.
>
> (Getting something into the build-and-boot testers might not be a bad
> idea, though).
0day runs make htmldocs on everything it can get its hand on. That was
about the first thing I've made sure happens when we went onto this docs
endeavor :-)
I guess 0day just isn't all that good at making sure people handle docs
issues in cross-tree conflicts, but hopefully that doesn't happen much in
the future anymore now that docbook is gone. The other problem is also
that the current htmldocs build is anything but clean (lots of warnings
about kernel-doc mismatching the function prototype, but lots others), and
we don't yet have anyone like Arnd trying to stem the tide ...
Wrt building: The big gain with sphinx is incremental builds: You can
finally edit a few comments/text, rebuild and a) not have to wait more
than a few seconds b) be sure it did rebuild everything that had to be
rebuild. Makes things much nicer for developers, not so much for
maintainers unfortunately, not sure how much faster we could make that.
-Daniel
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2017-07-15 9:04 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-07-03 13:20 [PULL] Docs for 4.13 Jonathan Corbet
2017-07-04 4:32 ` Linus Torvalds
2017-07-04 7:56 ` Markus Heiser
2017-07-04 19:24 ` Jonathan Corbet
2017-07-15 9:04 ` Daniel Vetter
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.