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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Several paths in the security/keys documentation were incorrect.
Signed-off-by: NJosh Holland <anowlcalledjosh@gmail.com>
Signed-off-by: NJonathan 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: NJian-Hong Pan <starnight@g.ncu.edu.tw>
Acked-by: NStefan Schmidt <stefan@osg.samsung.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There's no use for this blank line at the end of the file. Remove it.
Signed-off-by: NThierry Reding <treding@nvidia.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Update the ccflags-y example to match current usage.
Signed-off-by: NSedat Dilek <sedat.dilek@gmail.com>
Signed-off-by: NJonathan 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: NJames 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: NJonathan Corbet <corbet@lwn.net>

Documentation/process/submitting-patches.rst contains a non-ascii
character.  Change it to the ascii equivalent.
Signed-off-by: NFrank Rowand <frank.rowand@sony.com>
Signed-off-by: NJonathan 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: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that we have a script to check for Sphinx dependencies,
document it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

After removal of DocBook, those targets are bogus.
Reported-by: NJim Davis <jim.epost@gmail.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NZhouyi Zhou <zhouzhouyi@gmail.com>
Reviewed-by: NKieran Bingham <kbingham@kernel.org>
Acked-by: NJan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: NJonathan 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: NZhouyi Zhou <zhouzhouyi@gmail.com>
Signed-off-by: NJonathan 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: NJonathan 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: NJonathan 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: NJonathan 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: NJonathan 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: NJonathan 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: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJonathan 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: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJonathan 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: NGeert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan 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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

Pull documentation format standardization from Jonathan Corbet:
 "This series converts a number of top-level documents to the RST format
  without incorporating them into the Sphinx tree. The hope is to bring
  some uniformity to kernel documentation and, perhaps more importantly,
  have our existing docs serve as an example of the desired formatting
  for those that will be added later.

  Mauro has gone through and fixed up a lot of top-level documentation
  files to make them conform to the RST format, but without moving or
  renaming them in any way. This will help when we incorporate the ones
  we want to keep into the Sphinx doctree, but the real purpose is to
  bring a bit of uniformity to our documentation and let the top-level
  docs serve as examples for those writing new ones"

* tag 'standardize-docs' of git://git.lwn.net/linux: (84 commits)
  docs: kprobes.txt: Fix whitespacing
  tee.txt: standardize document format
  cgroup-v2.txt: standardize document format
  dell_rbu.txt: standardize document format
  zorro.txt: standardize document format
  xz.txt: standardize document format
  xillybus.txt: standardize document format
  vfio.txt: standardize document format
  vfio-mediated-device.txt: standardize document format
  unaligned-memory-access.txt: standardize document format
  this_cpu_ops.txt: standardize document format
  svga.txt: standardize document format
  static-keys.txt: standardize document format
  smsc_ece1099.txt: standardize document format
  SM501.txt: standardize document format
  siphash.txt: standardize document format
  sgi-ioc4.txt: standardize document format
  SAK.txt: standardize document format
  rpmsg.txt: standardize document format
  robust-futexes.txt: standardize document format
  ...

Pull random updates from Ted Ts'o:
 "Add wait_for_random_bytes() and get_random_*_wait() functions so that
  callers can more safely get random bytes if they can block until the
  CRNG is initialized.

  Also print a warning if get_random_*() is called before the CRNG is
  initialized. By default, only one single-line warning will be printed
  per boot. If CONFIG_WARN_ALL_UNSEEDED_RANDOM is defined, then a
  warning will be printed for each function which tries to get random
  bytes before the CRNG is initialized. This can get spammy for certain
  architecture types, so it is not enabled by default"

* tag 'random_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/tytso/random:
  random: reorder READ_ONCE() in get_random_uXX
  random: suppress spammy warnings about unseeded randomness
  random: warn when kernel uses unseeded randomness
  net/route: use get_random_int for random counter
  net/neighbor: use get_random_u32 for 32-bit hash random
  rhashtable: use get_random_u32 for hash_rnd
  ceph: ensure RNG is seeded before using
  iscsi: ensure RNG is seeded before use
  cifs: use get_random_u32 for 32-bit lock random
  random: add get_random_{bytes,u32,u64,int,long,once}_wait family
  random: add wait_for_random_bytes() API

Pull ->s_options removal from Al Viro:
 "Preparations for fsmount/fsopen stuff (coming next cycle). Everything
  gets moved to explicit ->show_options(), killing ->s_options off +
  some cosmetic bits around fs/namespace.c and friends. Basically, the
  stuff needed to work with fsmount series with minimum of conflicts
  with other work.

  It's not strictly required for this merge window, but it would reduce
  the PITA during the coming cycle, so it would be nice to have those
  bits and pieces out of the way"

* 'work.mount' of git://git.kernel.org/pub/scm/linux/kernel/git/viro/vfs:
  isofs: Fix isofs_show_options()
  VFS: Kill off s_options and helpers
  orangefs: Implement show_options
  9p: Implement show_options
  isofs: Implement show_options
  afs: Implement show_options
  affs: Implement show_options
  befs: Implement show_options
  spufs: Implement show_options
  bpf: Implement show_options
  ramfs: Implement show_options
  pstore: Implement show_options
  omfs: Implement show_options
  hugetlbfs: Implement show_options
  VFS: Don't use save/replace_mount_options if not using generic_show_options
  VFS: Provide empty name qstr
  VFS: Make get_filesystem() return the affected filesystem
  VFS: Clean up whitespace in fs/namespace.c and fs/super.c
  Provide a function to create a NUL-terminated string from unterminated data