The Sphinx transition is still creating a fair amount of work. Here we
have a number of fixes and, importantly, a proper PDF output solution,
thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.
I've started a couple of new books: a driver API book (based on the old
device-drivers.tmpl) and a development tools book. Both are meant to show
how we can integrate together our existing documentation into a more
coherent and accessible whole. It involves moving some stuff around and
formatting changes, but, I think, the results are worth it. The good news
is that most of our existing Documentation/*.txt files are *almost* in RST
format already; the amount of messing around required is minimal.
And, of course, there's the usual set of updates, typo fixes, and more.
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJX8st8AAoJEI3ONVYwIuV6d10P/0Zsnx3hSSx22aHxP4kVb4s/
NTttFAienYzc2fYYD3K/wMQbSbprW8Pp7uSP1suzAbU5FGgfLyDFQHnE0AVqFNiT
MHVc5oBWp4ZlvNcyQUeXOsKtb5Rin00XHjer2mm/T9HfgmCYR4i+C9HQuv+J94Jf
sgeI4IimvLjlp7dDbhcIfdqCpZ+UwBSpSm9w5f7astYDjocJHrkBqyk/46Ir4qz9
+2joNZRWMUatrQYJWMJnnvlnx8lHhkDjaL/Egy+f7ucpddEkbGvWvabGCSMtCyzS
CKlA53Y4wS59cNFkAuxsHjun4TcQhbZn/iBIM+8aOdameO0ksC4jSoND2P6N6vKF
dHkAkayP9ChW3k/J8D+3cGIJNFiaYevEXcgxLyShjCuh4t4yfOC9aIGUl3Ye9/mR
tiKpMsvzmwJ+yO+kzJsxWTmRAX5wdI1Z062ltiS1dmSbl3c3NgQFpfP7V7AJSQ7c
DzkuoUnGEqJOHm64dAZQuxL4jj6StzejjxlhH0bIjbNn1a9VlX9afwsdJaXA+kmr
jQHJtR0wD1mLMYYdvNEiqvcCbumG+kaXmH6eUQadRxruRdZyhi1Z6Ql1CtwQGtbR
SetC/MVxIN3fGPbZYhJ162xVjQ8OeX0ndRmRjy6SBDMoRGSKqi2IME8JAGOshxE0
0uYAJJFZOeiR6KaPnci/
=kGKl
-----END PGP SIGNATURE-----
Merge tag 'docs-4.9' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"This is the documentation update pull for the 4.9 merge window.
The Sphinx transition is still creating a fair amount of work. Here we
have a number of fixes and, importantly, a proper PDF output solution,
thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.
I've started a couple of new books: a driver API book (based on the
old device-drivers.tmpl) and a development tools book. Both are meant
to show how we can integrate together our existing documentation into
a more coherent and accessible whole. It involves moving some stuff
around and formatting changes, but, I think, the results are worth it.
The good news is that most of our existing Documentation/*.txt files
are *almost* in RST format already; the amount of messing around
required is minimal.
And, of course, there's the usual set of updates, typo fixes, and
more"
* tag 'docs-4.9' of git://git.lwn.net/linux: (120 commits)
URL changed for Linux Foundation TAB
dax : Fix documentation with respect to struct pages
iio: Documentation: Correct the path used to create triggers.
docs: Remove space-before-label guidance from CodingStyle
docs-rst: add inter-document cross references
Documentation/email-clients.txt: convert it to ReST markup
Documentation/kernel-docs.txt: reorder based on timestamp
Documentation/kernel-docs.txt: Add dates for online docs
Documentation/kernel-docs.txt: get rid of broken docs
Documentation/kernel-docs.txt: move in-kernel docs
Documentation/kernel-docs.txt: remove more legacy references
Documentation/kernel-docs.txt: add two published books
Documentation/kernel-docs.txt: sort books per publication date
Documentation/kernel-docs.txt: adjust LDD references
Documentation/kernel-docs.txt: some improvements on the ReST output
Documentation/kernel-docs.txt: Consistent indenting: 4 spaces
Documentation/kernel-docs.txt: Add 4 paper/book references
Documentation/kernel-docs.txt: Improve layouting of book list
Documentation/kernel-docs.txt: Remove offline or outdated entries
docs: Clean up bare :: lines
...
Task 11 (kernel-doc) still mentions usage of make manpages, but
this won't work if the API is documented via Sphinx. So, update
it to use either htmldocs or pdfdocs, with are the documentation
targets that work for all.
While here, add ReST reference to the kernel documentation book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add option 'name' to the "c:function:" directive. With option 'name'
the ref-name of a function can be modified. E.g.::
.. c:function:: int ioctl( int fd, int request )
:name: VIDIOC_LOG_STATUS
The func-name (e.g. ioctl) remains in the output but the ref-name
changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for
this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
can now referenced by::
:c:func:`VIDIOC_LOG_STATUS`
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx wants to interpret all literal blocks as being in the chosen
language and complains when an attempt to parse a block fails.
kernel-documentation.rst has a few blocks that are not in C; make that
explicit to shut down the associated warnings.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Implements the reST flat-table directive.
The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:
* column-span: with the role ``cspan`` a cell can be extended through
additional columns
* row-span: with the role ``rspan`` a cell can be extended through
additional rows
* auto span rightmost cell of a table row over the missing cells on the right
side of that table-row. With Option ``:fill-cells:`` this behavior can
changed from *auto span* to *auto fill*, which automaticly inserts (empty)
list tables
The *list tables* formats are double stage lists. Compared to the
ASCII-art they migth be less comfortable for readers of the
text-files. Their advantage is, that they are easy to create/modify
and that the diff of a modification is much more meaningfull, because
it is limited to the modified content.
The initial implementation was taken from the sphkerneldoc project [1]
[1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Describe Sphinx, reStructuredText, the kernel-doc extension, the
kernel-doc structured documentation comments, etc.
The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim
<twaugh@redhat.com>.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Linus Torvalds