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>

With Sphinx 1.6 nested numbering is reported as warning::

  ./input/joydev/index.rst:13: WARNING: input/joydev/joystick-api is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-func-open is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-func-close is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-func-ioctl is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-func-poll is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-ioc-adap-g-caps is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-ioc-adap-g-log-addrs is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-ioc-adap-g-phys-addr is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-ioc-dqevent is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-ioc-g-mode is already assigned section numbers (nested numbered toctree?)
  ./media/uapi/cec/cec-funcs.rst:8: WARNING: media/uapi/cec/cec-ioc-receive is already assigned section numbers (nested numbered toctree?)

TOC numbering is already set in::

  ./input/devices/index.rst:9:
  ./media/uapi/cec/cec-api.rst:19:

I guess the nested numbering in:

  ./input/joydev/index.rst
  ./media/uapi/cec/cec-funcs.rst

is just a C&P typo, so lets remove it.
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

This is a minor patch that fixes the following typo in the NVMEM documentation:

When a consumers no longer needs the NVMEM

to,

When a consumer no longer needs the NVMEM
Signed-off-by: Narendran Sankaran <naren.kernel@gmail.com>
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>

Right now, if the building system doesn't find Sphinx, it
bails out, without providing any instructions about what
should be done.

Instead, run a script, providing some guidance about the
steps needed for Sphinx build to work.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Several paths in the security/keys documentation were incorrect.
Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The function declaration in the lastest include/net/mac802154.h has been
changed since v3.19.

ieee802154_alloc_device => ieee802154_alloc_hw
ieee802154_free_device => ieee802154_free_hw
ieee802154_register_device => ieee802154_register_hw
ieee802154_unregister_device => ieee802154_unregister_hw

However, the description in the Device drivers API section of
Documentation/networking/ieee802154.txt is still in the state of
v3.18.63.
Signed-off-by: Jian-Hong Pan <starnight@g.ncu.edu.tw>
Acked-by: Stefan Schmidt <stefan@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There's no use for this blank line at the end of the file. Remove it.
Signed-off-by: Thierry Reding <treding@nvidia.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

RHEL 7.x and clone distros are shipped with Sphinx 1.1.x,
with is incompatible with Kernel ReST markups.

So, on those systems, the only alternative is to install
it via a Python virtual environment.

While seeking for "pip" on CentOS 7.3, I noticed that it
is not really needed, as python-virtualenv has its version
packaged there already. So, remove this from the list of
requirements for all distributions.

With regards to PDF, we need at least texlive-tabulary
extension, but that is not shipped there (at least on
CentOS). So, disable PDF packages as a whole.

Please notice, however, that texlive + amsmath is needed for
ReST to properly handle ReST ".. math::" tags. Yet, Sphinx
fall back to display the LaTeX math expressions as-is, if
such extension is not available.

So, let's just disable all texlive packages as a whole.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Update the ccflags-y example to match current usage.
Signed-off-by: Sedat Dilek <sedat.dilek@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Since commit 64e2a42b ("parisc: Add ARCH_TRACEHOOK and regset
support") in v4.7, parisc selects HAVE_ARCH_TRACEHOOK, so update its
entry in Documentation/features from TODO to ok.
Signed-off-by: James Hogan <james.hogan@imgtec.com>
Cc: "James E.J. Bottomley" <jejb@parisc-linux.org>
Cc: Helge Deller <deller@gmx.de>
Cc: Ingo Molnar <mingo@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/process/submitting-patches.rst contains a non-ascii
character.  Change it to the ascii equivalent.
Signed-off-by: Frank Rowand <frank.rowand@sony.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

A series to clean up a number of docs build warnings.  More to come.

Documentation/gpu/drm-mm.rst includes from include/drm/drm_syncobj.h with
:export:, but this is a header file without export directives.  That
results in this warning:

    ./include/drm/drm_syncobj.h:1: warning: no structured comments found

...and a failure to obtain the documentation from that file.  Switch to
:internal: instead to make both problems go away.

Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Mauro says:

Sphinx installation is not trivial, as not all versions are supported,
and it requires a lot of stuff for math, images and PDF/LaTeX output
to work.

So, add a script that checks if everything is fine, providing
distro-specific hints about what's needed for it to work.

Add support for detecting and installing missing packages
on Mageia. I opted to use "urpmi" at the install instructions,
as this is present on Mageia since ever. Yet, if I were using
Mageia 6, I would likely be using "dnf", as it is, IMHO,
easier to use.

Tested with Mageia 6.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Now that we have a script to check for Sphinx dependencies,
document it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Gentoo need some USE for GraphViz and ImageMagick to have
the features required by kfigure.py.

Output that when providing instructions for Gentoo.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ImageMagick actually uses librsvg for conversions when converiting
from SVG (actually, it uses rsvg-convert). That causes the build to
fail with:

	WARNING: Error #1 when calling: /usr/bin/convert /home/mchehab/docs/Documentation/media/uapi/v4l/selection.svg /home/mchehab/docs/Documentation/output/latex/selection.pdf
	convert: delegate failed `'rsvg-convert' -o '%o' '%i'' @ error/delegate.c/InvokeDelegate/1919.
	convert: unable to open file `/tmp/magick-8883oOQfHzrA5trM': No such file or directory @ error/constitute.c/ReadImage/544.

Add the corresponding dependencies.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

On newer versions of graphviz packaging on Fedora, it is needed to
install a separate package for PDF support.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Instead of using 3 commands to install a virtualenv, use
a single one, reading the requirements from this file:

	Documentation/sphinx/requirements.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Detect if the script runs after creating the virtualenv,
printing the command line commands to enable the virtualenv.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Solving Sphinx dependencies can be painful. Add a script to
check if everything is ok.

Tested on:
	- Fedora 25 and 26;
	- Ubuntu 17.04;
	- OpenSuse Tumbleweed;
	- Arch Linux;
	- Gentoo.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

After removal of DocBook, those targets are bogus.
Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit 6807c846 ("x86: Enable KASLR by default") enables KASLR
by default on x86. While KASLR will confuse gdb which resolve kernel
symbol address from symbol table of vmlinux. We should turn off KASLR for
kernel debugging.
Signed-off-by: Zhouyi Zhou <zhouzhouyi@gmail.com>
Reviewed-by: Kieran Bingham <kbingham@kernel.org>
Acked-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

commit 6807c846 ("x86: Enable KASLR by default") enables KASLR
by default on x86. While KASLR will confuse gdb which resolve kernel
symbol address from symbol table of vmlinux. We should turn off KASLR for
kernel debugging.
Signed-off-by: Zhouyi Zhou <zhouzhouyi@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The only function of interest in that file was scsi_print_status().  That
function was removed in commit 7ac70763 (scsi: remove
scsi_print_status()) but the docs were not changed to match, yielding this
warning:

    ./drivers/scsi/constants.c:1: warning: no structured comments found

There's nothing there anymore, so just remove that section from the docs.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Back in 2012, commit 9807f759 (UAPI: (Scripted) Disintegrate
arch/s390/include/asm) moved struct cmbdata (and its kerneldoc comments) to
another file, but did not update the docs to match.  The result is this
warning:

    ./arch/s390/include/asm/cmb.h:1: warning: no structured comments found

...and no documentation for that structure.  Update the docs to get the
information from the right place.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There are no kerneldoc comments in drivers/dma-buf/seqno-fence.c, and it
appears there never have been.  Stop looking for comments there to
eliminate this warning:

    ./drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

...because there are none there, and I cannot figure out what would ever
have been of interest there.  This eliminates this warning:

    ./kernel/sys.c:1: warning: no structured comments found

from the build.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The docs build complains:

    ./include/linux/init.h:1: warning: no structured comments found

The problem is that the comments in question were moved to module.h in
commit 0fd972a7 (module: relocate module_init from init.h to
module.h).  Fix basics.rst to match.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

In a code-block with line numbers (option :lineno:) there is a
misalignment of the rendered source code lines on the right side and the
line numbers on the left side.

  https://github.com/rtfd/sphinx_rtd_theme/issues/419

Since this issue is reported to the RTD theme project, it might be fixed
in the future (take this as a interim solution).
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

List items with two ore more blocks are not well rendered. E.g. the gap
between last block (l1-b2) of the first list item and the following list
item (L2) is to small::

    * L1 xxxxxxxxxx
      xxxxxxxxxxxxx

      l1-b2 xxxxxxx
      xxxxxxxxxxxxx
    * L2 xxxxxxxxxx
      xxxxxxxxxxxxx

So that it can be read more liquidly, a distance was added to the last
block (l1-b2)::

    * L1 xxxxxxxxxx
      xxxxxxxxxxxxx

      l1-b2 xxxxxxx
      xxxxxxxxxxxxx

    * L2 xxxxxxxxxx
      xxxxxxxxxxxxx
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

All low-level PM/SMP code using virt_to_phys() should actually use
__pa_symbol() against kernel symbols.  Update the documentation to move
away from virt_to_phys().

Cfr. commit 6996cbb2372189f7 ("ARM: 8641/1: treewide: Replace uses of
virt_to_phys with __pa_symbol")
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Instead of having it on just one note, add a separate section.

This way, we could later improve it, providing a better
guide about the needed steps for PDF builds.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

As we now have a document describing the install
requirements for Sphinx, add there the need for GraphViz
and ImageMagick.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

As the Sphinx build seems very fragile, specially for
PDF output, add a notice about how to use it on a virtual
environment.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The toolchain used by Sphinx is somewhat complex, and installing
it should be part of the doc-guide.

Move it out of changes.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The kfigure module doesn't work with Sphinx version 1.2. So,
update the minimal requirements accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>