The 80211.tmpl DocBook file was removed in commit 819bf593 ("docs-rst:
sphinxify 802.11 documentation"), but the 80211.xml target was re-added to
the Makefile by commit 7ddedebb ("ALSA: doc: ReSTize
writing-an-alsa-driver document"), leading to a failure when building the
documentation:

*** No rule to make target 'Documentation/DocBook/80211.xml', needed by
'Documentation/DocBook/80211.aux.xml'.

cc: stable@vger.kernel.org
Signed-off-by: NJohn Brooks <john@fastquake.com>
Mea-culpa-by: NJonathan Corbet <corbet@lwn.net>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

With the conversion of the documentation to Sphinx, the old DocBook is
now stale.
Signed-off-by: NStephan Mueller <smueller@chronox.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Convert the tracepoint docbook template to RST and add it to the core-api
manual.  No changes to the actual text beyond the mechanical formatting
conversion.

Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.

Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules.  It doesn't work here either :)

Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This is a conversion of the USB documentation to the Sphinx format.
No content was altered or reformatted.
Signed-off-by: NOliver <oneukum@suse.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Another simple conversion from DocBook to ReST.
This required a few manual fixups and reformats, but the most of
contents are kept as is.
Signed-off-by: NTakashi Iwai <tiwai@suse.de>

A simple conversion of alsa-driver-api document from DocBook to ReST.

It's moved to the new Documentation/sound/kernel-api subdirectory that
will contain other ALSA kernel API documents.

The GPL legal note was removed, as it's superfluous (and doesn't fit
with ReST kernel docs pretty well).
Signed-off-by: NTakashi Iwai <tiwai@suse.de>

Removes intermediate 'Documentation/DocBook/.*.xml.cmd' files

Changes since v1:
- Reduce the patch to DocBook cleandocs

References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.comReported-by: NJim Davis <jim.epost@gmail.com>
Signed-off-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This is just a very basic conversion, I've split up the original
multi-book template, and also split up the multi-part mac80211
part in the original book; neither of those were handled by the
automatic pandoc conversion.

Fix errors that showed up, resulting in a much nicer rendering,
at least for the interface combinations documentation.
Signed-off-by: NJohannes Berg <johannes.berg@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Sphinx supports LaTeX output. Sometimes, it is interesting to
call it directly, instead of also generating a PDF. As it comes
for free, add a target for it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Perform a basic sphinx conversion of the device-drivers docbook and move it
to its own directory.
Signed-off-by: NJonathan 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: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Instead of a separate ignore flag, use the obvious DOCBOOKS="" to ignore
all DocBook files. This is also in line with the Sphinx build being
ignored if a non-empty DOCBOOKS make variable is specified on the make
command line.

This replaces the IGNORE_DOCBOOKS introduced in

commit 54721886
Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Date:   Sat Jul 9 13:12:45 2016 -0300

    doc-rst: add an option to ignore DocBooks when generating docs

and aligns with

commit 6387872c
Author: Jani Nikula <jani.nikula@intel.com>
Date:   Fri Jul 1 15:24:44 2016 +0300

    Documentation/sphinx: skip build if user requested specific DOCBOOKS

Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
Tested-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that all media documentation was converted to Sphinx, we
should get rid of the old DocBook one, as we don't want people
to submit patches against the old stuff.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Sometimes, we want to do a partial build, instead of building
everything. However, right now, if one wants to build just
Sphinx books, it will build also the DocBooks.

Add an option to allow to ignore all DocBooks when building
documentation.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

The gpu documentation has now been converted to reStructuredText files
under Documentation/gpu. Remove the obsolete DocBook template. Also
remove it from MAINTAINERS.

Good riddance.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/8d673f75fe686371ed9838682c368a4e3b96bf54.1466506505.git.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: NJani Nikula <jani.nikula@intel.com>

When make htmldocs is called on non-verbose mode, it will still be
verbose with index.html generation for no good reason, printing:

	rm -rf Documentation/DocBook/index.html; echo '<h1>Linux Kernel HTML Documentation</h1>' >> Documentation/DocBook/index.html && echo '<h2>Kernel Version: 4.4.0-rc1</h2>' >> Documentation/DocBook/index.html && cat Documentation/DocBook/iio.html >> Documentation/DocBook/index.html

Instead, use the standard non-verbose mode, using:

	  HTML    Documentation/DocBook/index.html

if not called with V=1.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There's no build_images function to call. So remove it.

This is just a cleanup patch, with doesn't affect the build.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Sometimes, it is needed to compile only a subset of the possible
DocBooks. This is supported by the building system, but it is not
docummented. Add a documentation for it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

DRM is a lot more than a direct rendering manager nowadays, and there's
also a bunch of things worth documenting for gpu driver developers
outside of drivers/gpu/drm, like vgaarb, vga_switcheroo or the various
hardware buses like host1x and ipu-v3.

To avoid further confusion let's rename the top-level to reflect
reality.

And yes I'm already looking forward to when we need to replace the G
in GPU with a * ;-)

Inspired by a thread with Lukas since he refused to include the
vga_switcheroo docs into the drm docs because it's not drm.

Cc: Lukas Wunner <lukas@wunner.de>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
[Lukas: Drop BUG() easter egg in i915_gem_execbuffer.c spotted by Jani
and fix typos in commit message.]
Signed-off-by: NLukas Wunner <lukas@wunner.de>
Acked-by: NDave Airlie <airlied@gmail.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Currently the encoding of documents generated by DocBook depends on
the current locale.  Make the output reproducible independently of
the locale, by setting the encoding to UTF-8 (LC_CTYPE=C.UTF-8) by
preference, or ASCII (LC_CTYPE=C) as a fallback.

LC_CTYPE can normally be overridden by LC_ALL, but the top-level
Makefile unsets that.
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
[jc: added check-lc_ctype to .gitignore]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Functions, Structs and Parameters definitions on kernel documentation
are pure cosmetic, it only highlights the element.

To ease the navigation in the documentation we should use <links> inside
those tags so readers can easily jump between methods directly.

This was discussed in 2014[1] and is implemented by getting a list
of <refentries> from the DocBook XML to generate a database. Then it looks
for <function>,<structnames> and <paramdef> tags that matches the ones in
the database. As it only links existent references, no broken links are
added.

[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html
Signed-off-by: NDanilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some kernel-doc sections are included in multiple DocBook files.  This
means the mandocs target will generate the same manual page multiple
times with different metadata (author name/address and manual title,
taken from the including DocBook file).  If it's invoked in a parallel
build, the output is non-determinstic.

Build the manual pages in a separate subdirectory per DocBook file,
then sort and de-duplicate when installing them (which is serialised).
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
[jc: fixed conflicts with the docs tree]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This is intended to help developers faster find their way
inside the Industrial I/O core and reduce time spent on IIO
drivers development.
Signed-off-by: NDaniel Baluta <daniel.baluta@intel.com>
Acked-by: NCrt Mori <cmo@melexis.com>
Reviewed-by: NLars-Peter Clausen <lars@metafoo.de>
Signed-off-by: NJonathan Cameron <jic23@kernel.org>

This reverts commit b44158b1.  This commit
introduced warnings and possibly inconsistent results into the doc build
process.  The goal is good but it will need to be achieved another way.
Reported-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Install the man pages with mode 644 instead of 755
Signed-off-by: NJim Davis <jim.epost@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some kernel-doc sections are included in multiple DocBook files.  This
means the mandocs target will generate the same manual page multiple
times with different metadata (author name/address and manual title,
taken from the including DocBook file).  If it's invoked in a parallel
build, the output is nondeterminstic.

For each section that is duplicated, mark the less specific manual's
inclusion as 'extra' and exclude it during conversion to manual pages.
Use xmlif for this, as that is bundled with xmlto which we already
use.

I would have preferred to use more conventional markup for this, but
each of the following approaches failed:

1. Wrap the extra inclusions with a new element and add a template to
   the stylesheet to include/exclude them.  Unfortunately DocBook XSL
   doesn't seem to support foreign elements at an intermediate level
   in the document tree.
2. Use DocBook profiling.  This works but requires passing an absolute
   path to the profile stylesheet to xmlto, so it's not portable.
3. Use SGML marked sections.  docbook2x can handle these but xmlto
   chokes on them.
Reported-by: NJérémy Bobbio <lunar@debian.org>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The mtime on a man page is the build time.  As gzip stores the mtime
and original name in the compressed file by default, this makes
compressed man pages unreproducible.  Neither of these are important
metadata in this case, so turn this off.
Reported-by: NJérémy Bobbio <lunar@debian.org>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Use find + xargs to compress the generated manpages. Without this patch,
the build can fail with

    gzip -f Documentation/DocBook/man/*.9
    /bin/bash: /usr/bin/gzip: Argument list too long

This happened with qemu user mode emulation on aarch64.
Signed-off-by: NMichal Marek <mmarek@suse.cz>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add the crypto API documentation into the DocBook Makefile to allow it
being compiled
Signed-off-by: NStephan Mueller <smueller@chronox.de>
Signed-off-by: NHerbert Xu <herbert@gondor.apana.org.au>

Document the process of writing an musb glue layer by taking the
Ingenic JZ4740 glue layer as an example, as it seems more simple than
most glue layers due to the basic feature set of the JZ4740 USB device
controller.
Signed-off-by: NApelete Seketeli <apelete@seketeli.net>
Signed-off-by: NFelipe Balbi <balbi@ti.com>

The commit ec3fadd6 (kbuild: docbook: use $(obj) and $(src) rather
than specific path) replaces the specific path with $(src). But when
executing "make help", the $(src) is null and then causes an include
error. Fix it by restoring the specific path.
Signed-off-by: NKevin Hao <haokexin@gmail.com>
Signed-off-by: NMichal Marek <mmarek@suse.cz>

Signed-off-by: NMasahiro Yamada <yamada.m@jp.panasonic.com>
Signed-off-by: NMichal Marek <mmarek@suse.cz>

It is not a good idea to describe

  %.xml: %.tmpl FORCE
    ...

and

  $(BOOKS): $(KERNELDOC)

separately. This cannot detect missing template files.

For example, add something to DOCBOOKS variable:
  DOCBOOKS += foobar.xml
and run
  make xmldocs

It will succeed even if Documention/DocBook/foobar.tmpl
does not exist.
Signed-off-by: NMasahiro Yamada <yamada.m@jp.panasonic.com>
Signed-off-by: NMichal Marek <mmarek@suse.cz>

Signed-off-by: NMasahiro Yamada <yamada.m@jp.panasonic.com>
Signed-off-by: NMichal Marek <mmarek@suse.cz>

Switch the code documentation format style to DocBook format, enable
DocBook documentation generation, and fix some comments.
Signed-off-by: NDavid Fries <David@Fries.net>
Acked-by: NEvgeniy Polyakov <zbr@ioremap.net>
Signed-off-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>

Two concurrent calls to cmd_db2man may attempt to compress manual
pages generated by each other.  gzip can then fail due to an input
file having already been compressed and removed.

Move the gzip command to the top-level mandocs target.
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Cc: Bastian Blank <waldi@debian.org>
Acked-by: NRob Landley <rob@landley.net>
Signed-off-by: NJiri Kosina <jkosina@suse.cz>

Trying to generate xhtml causes all functions to show up with a prefix
of "fsfunc" in the output, so just back off to html until someone
fixes the toolchain.

Note that this is not a problem with kernel-doc, it's an issue with
however "xmlto" renders xhtml output.
Signed-off-by: NRobert P. J. Day <rpjday@crashcourse.ca>
Acked-by: NRob Landley <rob@landley.net>
Signed-off-by: NJiri Kosina <jkosina@suse.cz>