The current documentation build looks like this:
$ make htmldocs
SPHINX htmldocs --> file:///home/willy/kernel/linux-next/Documentation/output
make[2]: Nothing to be done for 'html'.
WARNING: The kernel documentation build process
support for Sphinx v3.0 and above is brand new. Be prepared for
possible issues in the generated output.
$
That extra indentation before my next prompt isn't pretty. This patch
fixes it, but I'm not a pythonista, and maybe there's a better way.
Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Link: https://lore.kernel.org/r/20210215161757.GD2858050@casper.infradead.org
[jc: tweaked for the "better way"]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
As promised, drop support for some ancient sphinx releases, along with a
lot of the cruft that was required to make that support work.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
number of warnings from the once-noisy docs build process is nearly zero.
Getting to this point has required a lot of work; once there, hopefully we
can keep things that way.
I have packaged this as a separate pull because it does a fair amount of
reaching outside of Documentation/. The changes are all in comments and in
code placement. It's all been in linux-next since last week.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl+hscQPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5YgZAH/0JeDA/1VLZYYTmdABz8mjBZsoW9tyPGGztF
nsh5ykdHhL3MeTRwumW5armLVrfKhd1XT+nIzD7OcWlqu+RDOvQ5I95rahr473hP
1SHTjqm3/AlJwQoeS72X5U6QEJQ58e2IwCbP23H3x7I3Q3snEA/HhswzxurfoB/Z
j81YzDV2YPEc0LJWZ5Vn0NEdwP8cdpFv5rojsQmepq7K0yJ7tEHb7/u2cEuUBgXS
8LcYCNPLpiN+q5N8uQ5oDjIUNdLQvP03kgKtQWiCTr4BRydOrDlJie28LIedamEz
anu7UfaVK4bxn+ugRI0g2+aWQKux81ULCinKUWmLRNbcxjhaQqQ=
=hDfp
-----END PGP SIGNATURE-----
Merge tag 'docs-5.10-warnings' of git://git.lwn.net/linux
Pull documentation build warning fixes from Jonathan Corbet:
"This contains a series of warning fixes from Mauro; once applied, the
number of warnings from the once-noisy docs build process is nearly
zero.
Getting to this point has required a lot of work; once there,
hopefully we can keep things that way.
I have packaged this as a separate pull because it does a fair amount
of reaching outside of Documentation/. The changes are all in comments
and in code placement. It's all been in linux-next since last week"
* tag 'docs-5.10-warnings' of git://git.lwn.net/linux: (24 commits)
docs: SafeSetID: fix a warning
amdgpu: fix a few kernel-doc markup issues
selftests: kselftest_harness.h: fix kernel-doc markups
drm: amdgpu_dm: fix a typo
gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
drm: amdgpu: kernel-doc: update some adev parameters
docs: fs: api-summary.rst: get rid of kernel-doc include
IB/srpt: docs: add a description for cq_size member
locking/refcount: move kernel-doc markups to the proper place
docs: lockdep-design: fix some warning issues
MAINTAINERS: fix broken doc refs due to yaml conversion
ice: docs fix a devlink info that broke a table
crypto: sun8x-ce*: update entries to its documentation
net: phy: remove kernel-doc duplication
mm: pagemap.h: fix two kernel-doc markups
blk-mq: docs: add kernel-doc description for a new struct member
docs: userspace-api: add iommu.rst to the index file
docs: hwmon: mp2975.rst: address some html build warnings
docs: net: statistics.rst: remove a duplicated kernel-doc
docs: kasan.rst: add two missing blank lines
...
As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.
Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
After the build fix patches, it is believed that the output
with Sphinx 3.x won't be a problem. Still, the C domain
support was re-written, and this can have caused hidden
issues.
So, let's keep the warning, changing it to a lighter
warning text.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Sphinx C parser for the C domain is now more pedantic when
trying to identify the function types. That prevents scope
macros to be used as type defines.
Yet, since 3.0.2, it is possible to provide it a list of
such macros. Add them, in order to solve several Sphinx 3.x
warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
The Sphinx 3.x upgrade broke a number of things in our special "cdomain"
module that are not easy to fix. For now, just disable that module for the
3.x build and put out a warning that the build will not be perfect.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.
Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.
Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The building system can auto-generate a list of documents since
commit: 9d42afbe6b ("docs: pdf: add all Documentation/*/index.rst to PDF output").
The added logic there allows keeping the existing list, but
there's not real reason to keep it. Now, the media document
has gone (it was split into tree).
So, it sounds about time to get rid of the manual entries,
and let the script to generate it automatically instead.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.
However, on its default, it has two serious problems:
1) the namespace is global. So, two files with different
"introduction" section would create a label with the
same name. This is easily solvable by forcing the extension
to prepend the file name with:
autosectionlabel_prefix_document = True
2) It doesn't work hierarchically. So, if there are two level 1
sessions (let's say, one labeled "open" and another one "ioctl")
and both have a level 2 "synopsis" label, both section 2 will
have the same identical name.
Currently, there's no way to tell Sphinx to create an
hierarchical reference like:
open / synopsis
ioctl / synopsis
This causes around 800 warnings. So, the fix should be to
not let autosectionlabel to produce references for anything
that it is not at a chapter level within any doc, with:
autosectionlabel_maxdepth = 2
Fixes: 58ad30cf91 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references. Enable the autosection extension (available since
Sphinx 1.4) to make this work.
Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it>
Fixes: fcfacb9f83 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
In order to have the MAINTAINERS file visible in the rendered ReST
output, this makes some small changes to the existing MAINTAINERS file
to allow for better machine processing, and adds a new Sphinx directive
"maintainers-include" to perform the rendering.
Features include:
- Per-subsystem reference links: subsystem maintainer entries can be
trivially linked to both internally and external. For example:
https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing
- Internally referenced .rst files are linked so they can be followed
when browsing the resulting rendering. This allows, for example, the
future addition of maintainer profiles to be automatically linked.
- Field name expansion: instead of the short fields (e.g. "M", "F",
"K"), use the indicated inline "full names" for the fields (which are
marked with "*"s in MAINTAINERS) so that a rendered subsystem entry
is more human readable. Email lists are additionally comma-separated.
For example:
SECURE COMPUTING
Mail: Kees Cook <keescook@chromium.org>
Reviewer: Andy Lutomirski <luto@amacapital.net>,
Will Drewry <wad@chromium.org>
SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp
Status: Supported
Files: kernel/seccomp.c include/uapi/linux/seccomp.h
include/linux/seccomp.h tools/testing/selftests/seccomp/*
tools/testing/selftests/kselftest_harness.h
userspace-api/seccomp_filter
Content regex: \bsecure_computing \bTIF_SECCOMP\b
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
If we try to build a book with asian characters with XeLaTeX
and the font is not available, it will produce an error.
So, instead, add a logic at conf.py to detect if the proper
font is installed.
This will avoid an error while building the document, although
the result may not be readable.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
In order to be able to output Asian symbols with XeLaTeX, we
need the xeCJK package, and a default font for CJK symbols.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Currently, all index files should be manually added to the
latex_documents array at conf.py.
While this allows fine-tuning some LaTeX specific things, like
the name of the output file and the name of the document, it
is not uncommon to forget adding new documents there.
So, add a logic that will seek for all Documentation/*/index.rst.
If the index is not yet at latex_documents, it includes using
a reasonable default.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
The handling of dashes in particular results in confusing
documentation in a number of instances, since "--" becomes an
en-dash. This disables SmartyPants wholesale, losing smart quotes
along with smart dashes.
With Sphinx 1.6 we could fine-tune the conversion, using the new
smartquotes and smartquotes_action settings.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Our version check in Documentation/conf.py never envisioned a world where
Sphinx moved beyond 1.x. Now that the unthinkable has happened, fix our
version check to handle higher version numbers correctly.
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
readability improvements for the formatted output, some LICENSES updates
including the addition of the ISC license, the removal of the unloved and
unmaintained 00-INDEX files, the deprecated APIs document from Kees, more
MM docs from Mike Rapoport, and the usual pile of typo fixes and
corrections.
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJbztcuAAoJEI3ONVYwIuV6nTAP/0Be+5dNPGJmSnb/RbkwBuBV
zAFVUj2sx4lZlRmWRZ0r7AOef2eSw3IvwBix/vnmllYCVahjp+BdRbhXQAijjyeb
FWWjOH50/J+BaxSthAINiLRLvuoe0D/M08OpmXQfRl5q0S8RufeV3BDtEABx9j2n
IICPGTl8LpPUgSMA4cw8zPhHdauhZpbmL2mGE9LXZ27SJT4S8lcHMwyPU1n5S+Jd
ChEz5g9dYr3GNxFp712pkI5GcVL3tP2nfoVwK7EuGf1tvSnEnn2kzac8QgMqorIh
xB2+Sh4XIUCbHYpGHpxIniD+WI4voNr/E7STQioJK5o2G4HTuxLjktvTezNF8paa
hgNHWjPQBq0OOCdM/rsffONFF2J/v/r7E3B+kaRg8pE0uZWTFaDMs6MVaL2fL4Ls
DrFhi90NJI/Fs7uB4sriiviShAhwboiSIRXJi4VlY/5oFJKHFgqes+R7miU+zTX3
2qv0k4mWZXWDV9w1piPxSCZSdRzaoYSoxEihX+tnYpCyEcYd9ovW/X1Uhl/wCWPl
Ft+Op6rkHXRXVfZzTLuF6PspZ4Udpw2PUcnA5zj5FRDDBsjSMFR31c19IFbCeiNY
kbTIcqejJG1WbVrAK4LCcFyVSGxbrr281eth4rE06cYmmsz3kJy1DB6Lhyg/2vI0
I8K9ZJ99n1RhPJIcburB
=C0wt
-----END PGP SIGNATURE-----
Merge tag 'docs-4.20' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"This is a fairly typical cycle for documentation. There's some welcome
readability improvements for the formatted output, some LICENSES
updates including the addition of the ISC license, the removal of the
unloved and unmaintained 00-INDEX files, the deprecated APIs document
from Kees, more MM docs from Mike Rapoport, and the usual pile of typo
fixes and corrections"
* tag 'docs-4.20' of git://git.lwn.net/linux: (41 commits)
docs: Fix typos in histogram.rst
docs: Introduce deprecated APIs list
kernel-doc: fix declaration type determination
doc: fix a typo in adding-syscalls.rst
docs/admin-guide: memory-hotplug: remove table of contents
doc: printk-formats: Remove bogus kobject references for device nodes
Documentation: preempt-locking: Use better example
dm flakey: Document "error_writes" feature
docs/completion.txt: Fix a couple of punctuation nits
LICENSES: Add ISC license text
LICENSES: Add note to CDDL-1.0 license that it should not be used
docs/core-api: memory-hotplug: add some details about locking internals
docs/core-api: rename memory-hotplug-notifier to memory-hotplug
docs: improve readability for people with poorer eyesight
yama: clarify ptrace_scope=2 in Yama documentation
docs/vm: split memory hotplug notifier description to Documentation/core-api
docs: move memory hotplug description into admin-guide/mm
doc: Fix acronym "FEKEK" in ecryptfs
docs: fix some broken documentation references
iommu: Fix passthrough option documentation
...
My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation. Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.
Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.
For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Acked-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move the ext4 data structures book to Documentation/filesystems/ext4/
since the administrative information moved elsewhere.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
Move the ext4 mount option and other administrative stuff to the Linux
administrator's guide.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
The documentation build scripts won't build a pdf for the ext4
documentation unless explicitly called for, so ask for a separate
ext4.pdf to be generated with all the documentation.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
Import the chapter about inode data fork from the on-disk format wiki
page into the kernel documentation.
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
This warning will happen for every normal kernel docs build and doesn't
carry any useful information. Should anybody actually depend on this
"version" variable (which isn't clear to me), the "unknown version" value
will be clue enough.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Only the media PDF book was requiring adjustbox, in order to
scale big tables. That worked pretty good with Sphinx versions
1.4 and 1.5, but Spinx 1.6 changed the way tables are produced,
by introducing some weird macros before tabulary.
That causes adjustbox to fail. So, it can't be used anymore,
and its usage was removed from the media book.
So, let's remove it from conf.py and sphinx-pre-install.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx 1.5 added a new way to change backward colors for note
boxes, but kept backward compatibility with 1.4. On Sphinx 1.6,
the old way stopped working, in favor of a new less hackish
way.
Unfortunately, this is currently too buggy to be used, and
the old way doesn't work anymore. So, we have no option but
to stick with boring notice boxes.
One example of such bug is the notice that it is inside
struct v4l2_plane, at the "bytesused" field.
At least, add a notice about how to use, as maybe some day
the bug will vanish.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Only the media book used this extension in the past, but
it is not required anymore.
Cleanup patch only.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
On Sphinx 1.6, fancy boxes are used for verbatim. The sphinx.sty
sets verbatim font is always \small. That causes a problem
inside tables that use smaller fonts, as it can be too big for
the box.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
according to what Documentation/doc-guide/sphinx.rst says::
The ReST markups currently used by the Documentation/ files
are meant to be built with ``Sphinx`` version 1.3 or upper.
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currently, on Sphinx up to version 1.4, pdf output uses a vertical
margin of 1 inch. For upper versions, it uses a margin of 0.5 inches.
That causes both page headers and footers to be very close to the margin
of the sheet. Not all printers support writing like that.
Also, there's no reason why the layout for newer versions would be
different than for previous ones.
So, standardize it, by always setting to 1 inch.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 85c21e5c3e (docs-rst: better adjust margins and font size) added a
\usepackage{geometry} that conflicts with another inclusion deep within the
dependencies with newer versions of Sphinx, causing the the PDF build to fail
with a "conflicting parameters" error.
Detect the Sphinx version, using sphinxsetup for Sphinx versions 1.5 and
upper.
Fixes: 85c21e5c3e
[jc: Tweaked logic to exclude 1.5.x for x < 3 ]
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Otherwise we get PDF build failures when LaTeX refused to acknowledge the
existence of \ifthenelse
Fixes: 41cff161fe
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The userspace API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The sound subsystem book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The dev-tools API book was added without the bits required to
generate PDF output at the main conf.py. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The crypto API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
There's no kernel-documentation.rst file at Documentation/
anymore. So, remove it from the list of LaTeX-generated
documents.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
As we add more documents, it makes more sense to sort the
entries there in alphabetical order, as it makes easier to
check if something is not there.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
- Manually adjusted to use ..note and ..warning
- Minor fixes for it to be parsed without errors
- Use **bold** for emphasis.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Pull input subsystem updates from Dmitry Torokhov:
- a big update from Mauro converting input documentation to ReST format
- Synaptics PS/2 is now aware of SMBus companion devices, which means
that we can now use native RMI4 protocol to handle touchpads, instead
of relying on legacy PS/2 mode.
- we removed support from BMA180 accelerometer from input devices as it
is now handled properly by IIO
- update to TSC2007 to corretcly report pressure
- other miscellaneous driver fixes.
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (152 commits)
Input: ar1021_i2c - use BIT to check for a bit
Input: twl4030-pwrbutton - use input_set_capability() helper
Input: twl4030-pwrbutton - use correct device for irq request
Input: ar1021_i2c - enable touch mode during open
Input: add uinput documentation
dt-bindings: input: add bindings document for ar1021_i2c driver
dt-bindings: input: rotary-encoder: fix typo
Input: xen-kbdfront - add module parameter for setting resolution
ARM: pxa/raumfeld: fix compile error in rotary controller resources
Input: xpad - do not suggest writing to Dominic
Input: xpad - don't use literal blocks inside footnotes
Input: xpad - note that usb/devices is now at /sys/kernel/debug/
Input: docs - freshen up introduction
Input: docs - split input docs into kernel- and user-facing
Input: docs - note that MT-A protocol is obsolete
Input: docs - update joystick documentation a bit
Input: docs - remove disclaimer/GPL notice
Input: fix "Game console" heading level in joystick documentation
Input: rotary-encoder - remove references to platform data from docs
Input: move documentation for Amiga CD32
...
Now that all files under Documentation/input follows the ReST markup
language, rename them to *.rst and create a book for the Linux Input
subsystem.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Using the development version of sphinx caused the parsing of the
version to fail.
Signed-off-by: Rémy Léone <remy.leone@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
With Sphinx 1.5.3 I get the warning:
WARNING: primary_domain 'C' not found, ignored.
It seems that domain names in Sphinx are case-sensitive and for the C
domain the name must be lower case.
Signed-off-by: John Keeping <john@metanate.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.
The solution is to redefine the \DURole macro.
However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.
Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -C Documentation/output/./latex
Fixes: e61a39baf7 ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Set the default highlight language to "none", i.e. do not try to guess
the language and do automatic syntax highlighting on literal blocks.
Eyeballing around the generated documentation, we don't seem to actually
have a lot of literal blocks that would benefit from syntax
highlighting. The C code blocks we do have are typically very short, and
most of the literal blocks are things that shouldn't be highlighted (or,
do not have a pygments lexer). This seems to be true for literal blocks
both in the rst source files and in source code comments.
Not highlighting code is never wrong, but guessing the language wrong
almost invariably leads to silly or confusing highlighting.
At the time of writing, admin-guide/oops-tracing.rst and
admin-guide/ramoops.rst contain good examples of 1) a small C code
snippet not highlighted, 2) a hex dump highligted as who knows what, 3)
device tree block highlighted as C or maybe Python, 4) a terminal
interaction highlighted as code in some language, and finally, 5) some C
code snippets correctly identified as C. I think we're better off
disabling language guessing, and going by explicitly identified
languages for longer code blocks.
It is still possible to enable highlighting on an rst source file basis
using the highlight directive:
.. higlight:: language
and on a literal block basis using the code-block directive:
.. code-block:: language
See http://www.sphinx-doc.org/en/latest/markup/code.html for details.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Cc: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.
As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Python module names should not have hyphens per [PEP 8]. Drop the hyphen
from kernel-doc.py. The extension directive remains unchanged.
[PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names
Reported-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJX/QbjAAoJEAhfPr2O5OEVDKkP/30o73ZhzBkDR3xgApbmVdrw
1NQYZq8UKibZ87hv949535N3lwaHFV0mA8ylheu2MMArd1GoZvyXKqNbJN9316kQ
mSI8wVK77UiBP7RRolEepCuliQExNmayUm+kNZEZsF67+flilkcumCBqlPf114Sl
ruhpGTSAIz2mgbxGsPkFiN+4xl2AZFOjiiHsp9doBE8HAtEp3PyCrPv5T6zkK7PQ
KKf7ribcIB65tx0zBmhkfJOef/mqK/t7XgQS7kVRB3G4zr1nkh4g2iw/QbUreBtE
94p1VYAMBFfpCNe1rWaaBOxYRLsDBMQHz2LvOvj8HZKrsuBCKQQ4jAoYQ4bNi8cu
nWAb5Z19npoxJRYCGrPs8MJtCFD1IoT4zjiA8Ld5BT4SqBsCQ6VrgiUpQESzjtlj
Xp7V1D2ak3vx40FAuDGZsb7JwGTuIrK18rZyKSjvHbnydWiJlaHY9kR3lOe91wc2
MZOiD3K4lM5Lvse07nLVgOTjXW1fC3ScliRCQVLU/Wbm6A8UKiejES8sy0bFk9sU
8Go3RaAPVeQLGFLqOJG+6yu7sJ1FCZzAthKbpxtY8p/iKZE4QO0n4Y6Q2NjcjHJt
lDKYp83jne+AMthbLR+Ab6IL2GoOxaW6fnTrDioDxGc9Cvba90xYsZCIxbcGrM4h
cu1bOLUp5Ei1wHvaqRla
=JqCR
-----END PGP SIGNATURE-----
Merge tag 'media/v4.9-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab:
- Documentation improvements: conversion of all non-DocBook documents
to Sphinx and lots of fixes to the uAPI media book
- New PCI driver for Techwell TW5864 media grabber boards
- New SoC driver for ATMEL Image Sensor Controller
- Removal of some obsolete SoC drivers (s5p-tv driver and soc_camera
drivers)
- Addition of ST CEC driver
- Lots of drivers fixes, improvements and additions
* tag 'media/v4.9-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (464 commits)
[media] ttusb_dec: avoid the risk of go past buffer
[media] cx23885: Fix some smatch warnings
[media] si2165: switch to regmap
[media] si2165: use i2c_client->dev instead of i2c_adapter->dev for logging
[media] si2165: Remove legacy attach
[media] cx231xx: attach si2165 driver via i2c_client
[media] cx231xx: Prepare for attaching new style i2c_client DVB demod drivers
[media] cx23885: attach si2165 driver via i2c_client
[media] si2165: support i2c_client attach
[media] si2165: avoid division by zero
[media] rcar-vin: add R-Car gen2 fallback compatibility string
[media] lgdt3306a: remove 20*50 msec unnecessary timeout
[media] cx25821: Remove deprecated create_singlethread_workqueue
[media] cx25821: Drop Freeing of Workqueue
[media] cxd2841er: force 8MHz bandwidth for DVB-C if specified bw not supported
[media] redrat3: hardware-specific parameters
[media] redrat3: remove hw_timeout member
[media] cxd2841er: BER and SNR reading for ISDB-T
[media] dvb-usb: avoid link error with dib3000m{b,c|
[media] dvb-usb: split out common parts of dibusb
...
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
...
Now that the files at Documentation/development-process/
were converted to ReST, make create a book at Sphinx.
As we'll have other books related to the development process,
we'll add it as a sub-book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Now that the build of PDF output on media got fixed, re-add it
to the Sphinx PDF build.
Partially reverts 3eb6cd6834 ('Documentation: exclude
media documentation from pdf generation').
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
We need adjustbox to allow adjusting the size of tables that
are bigger than the line width. There are quite a few of them
at the media books.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When XeLaTeX is in interactive mode, it complains that
py@noticelength already exists. Rename it and declare it
only once to avoid such messages.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Instead of painting the box with gray, let's use a colored
box. IMHO, that makes easier to warn users about some issue
pointed by the Sphinx. It also matches to what we do already
with the HTML output.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
While the current implementation works well when using as a
paragraph, it doesn't work properly if inside a table. As we
have quite a few such cases, fix the logic to take the column
size into account.
PS.: I took the logic there from the latest version of Sphinx.sty
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add a sphinx-extension to customize the sphinx c-domain. No functional
changes right yet, just the boilerplate code.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This extension will be used by the media books.
The name of the math image extension changed on Sphinx 1.4.x,
according with:
http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmath
Let's autodetect, to keep building with versions < 1.4.
Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
As we have big tables, reduce the left/right margins and decrease
the point size to 8pt. Visually, it is still good enough, and
now less tables are too big to be displayed.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
pdflatex doesn't accept using some UTF-8 chars, like
"equal or less than" or "equal or greater than" chars. However,
the media documents use them. So, we need to use XeLaTeX for
conversion, and a font that accepts such characters.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Portrait is too small for some tables used at the media docs.
So, allow documents to tell Sphinx to generate some pages
in landscape by using:
.. raw:: latex
\begin{landscape}
<some stuff>
.. raw:: latex
\end{landscape}
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The usage of rst2pdf was replaced by pdflatex on a previous
patch. Remove the left-over code at conf.py.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.
* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF
Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::
make SPHINXDIRS="media gpu" htmldocs
To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::
make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs
With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Although pdflatex is more robust than rst2pdf, building media
documentation pdf still fails. Exclude media documentation from pdf
generation for now.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This should eliminate a whole class of markup warnings, at the cost of
occasionally amusing markup choices; we'll have to see if it works out.
Suggested-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The rst2pdf tool is a very broken toolchain, with is not capable
of parsing complex documents. As such, it doesn't build the
media book, failing with:
[ERROR] pdfbuilder.py:130 too many values to unpack
(using rst2pdf version 0.93.dev-r0 and Sphinx version 1.4.5)
So, make it build only the books we know that are safe to build.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
--
Btw, with the standard Sphinx version shipped on Fedora 24 (Sphinx
1.3.1), rst2pdf doesn't build even the simple kernel-documentation,
failing with this error:
writing Kernel... [ERROR] pdfbuilder.py:130 list index out of range
This is a known bug:
https://github.com/sphinx-doc/sphinx/issues/1844
So, maybe we should just disable pdf generation from RST for good,
as I suspect that maintaining it with a broken toolchain will be a
big headache.
Implements the minimal boilerplate for Sphinx HTML theme customization.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
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>
Read the version and release from the top level Makefile (for use when
Sphinx is invoked directly, by e.g. Read the Docs), but override them
via Sphinx command line arguments in a normal documentation build.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tell Sphinx where to find the extension, and pass on the kernel src tree
and kernel-doc paths to the extension.
With this, any .rst files under Documentation may contain the kernel-doc
rst directive to include kernel-doc documentation from any source file.
While building, it may be handy to pass kernel-doc extension
configuration on the command line. For example, 'make SPHINXOPTS="-D
kerneldoc_verbosity=0" htmldocs' silences all stderr output from
kernel-doc when the kernel-doc exit code is 0. (The stderr will be
logged unconditionally when the exit code is non-zero.)
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Add basic configuration and makefile to build documentation from any
.rst files under Documentation using Sphinx. For starters, there's just
the placeholder index.rst.
At the top level Makefile, hook Sphinx documentation targets alongside
(but independent of) the DocBook toolchain, having both be run on the
various 'make *docs' targets.
All Sphinx processing is placed into Documentation/Makefile.sphinx. Both
that and the Documentation/DocBook/Makefile are now expected to handle
all the documentation targets, explicitly ignoring them if they're not
relevant for that particular toolchain. The changes to the existing
DocBook Makefile are kept minimal.
There is graceful handling of missing Sphinx and rst2pdf (which is
needed for pdf output) by checking for the tool and python module,
respectively, with informative messages to the user.
If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but
otherwise gracefully fall back to the Sphinx default theme, with an
informative message to the user, and slightly less pretty HTML output.
Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available),
epubdocs and xmldocs targets. The output documents are written into per
output type subdirectories under Documentation/output.
Finally, you can pass options to sphinx-build using the SPHINXBUILD make
variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose
output from Sphinx.
This is based on the original work by Jonathan Corbet, but he probably
wouldn't recognize this as his own anymore.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
