Commit Graph

37 Commits

Author SHA1 Message Date
Rémy Léone
62924fd789 Add a target to check broken external links in the Documentation
Documentation shouldn't have broken links.
sphinx linkcheck builder scans all documents for external links, tries
to open them with urllib2, and writes an overview which ones are broken
and redirected to standard output and to output.txt in the output
directory.

Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Rémy Léone <remy.leone@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-15 15:22:47 -07:00
Jim Davis
c33dea1eda Documentation: make Makefile.sphinx no-ops quieter
Silence the "make[1]: Nothing to be done for ..." messages for the
no-op targets in Makefile.sphinx.

Signed-off-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-12 15:21:25 -07:00
Jonathan Corbet
f161e9a270 Merge branch 'ben' into docs-next
Ben writes: "This series fixes some bugs I found in the new doc build system."
2017-02-06 09:05:31 -07:00
Ben Hutchings
4b0b0d9d05 doc-rst: Fix recursive make invocation from macros
In any case where we recurse but don't mention $(MAKE) literally in
the recipe, we need to add a '+' at the start of the command to ensure
that parallel makes and various other options work properly.

Fixes: 609afe6b49 ("Documentation/sphinx: build the media intermediate ...")
Tested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-06 09:03:59 -07:00
Ben Hutchings
85bd9020d8 doc-rst: Break shell command sequences on failure
As $(SHELL) doesn't include the -e option, any loop or other sequence
needs to include explicit checks for failing commands.

Fixes: 609afe6b49 ("Documentation/sphinx: build the media intermediate ...")
Fixes: 606b9ac81a ("doc-rst: generic way to build only sphinx sub-folders")
Fixes: cd21379b16 ("doc-rst: generic way to build PDF of sub-folders")
Tested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-06 09:03:36 -07:00
Jani Nikula
c8929258a5 Documentation/sphinx: make targets independent of Sphinx work for HAVE_SPHINX=0
Make targets that don't depend on Sphinx work without warnings about
missing Sphinx. 'make cleandocs' will work without Sphinx just fine, and
the targets that are no-ops for Sphinx should just be skipped. Move them
outside of the HAVE_SPHINX checks to take precedence over the .DEFAULT
target for HAVE_SPHINX=0.

Reported-by: Jim Davis <jim.epost@gmail.com>
Reference: http://lkml.kernel.org/r/CA+r1ZhjRVqkjPXGOGB_BOAX2Hkfb+qQCtTzFfBMFeH1Mfeej7w@mail.gmail.com
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-01 13:10:54 -07:00
Markus Heiser
7cabd5ac69 doc-rst: fixed cleandoc target when used with O=dir
The cleandocs target won't work if I use a different output folder::

  $ make O=/tmp/kernel SPHINXDIRS="process" cleandocs
  make[1]: Entering directory '/tmp/kernel'
  make[3]: *** No rule to make target 'clean'.  Stop.
  ... Documentation/Makefile.sphinx💯 recipe for target 'cleandocs' failed

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-01 13:09:45 -07:00
Jani Nikula
2a0f4038a4 Documentation/sphinx: prevent generation of .pyc files in the source tree
Use PYTHONDONTWRITEBYTECODE=1 to prevent python from creating .pyc files
in the source tree. Python 3.2 has a __pycache__ scheme [1], but before
that the only alternative seems to be to copy the source files to the
build tree to ensure the .pyc files are created there too. Just prevent
.pyc file generation for simplicity.

Considering the small amount of python code to compile (assuming sphinx
itself has .pyc around), the impact on build is neglible.

[1] http://stackoverflow.com/questions/3522079/changing-the-directory-where-pyc-files-are-created

References: http://lkml.kernel.org/r/CAMuHMdVxqpH7-9XJ+YE_pgoA+-fe0969cSkOehYh3uubYcrhZA@mail.gmail.com
Reported-by: Geert Uytterhoeven <geert@linux-m68k.org>
References: http://lkml.kernel.org/r/1485816692.2900.17.camel@decadent.org.uk
Reported-by: Ben Hutchings <ben@decadent.org.uk>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-01 13:03:58 -07:00
Mauro Carvalho Chehab
293fbd4fef docs-rst: fix media cleandocs target
The builddir prefix was missing on make cleandocs. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:08:03 -07:00
Mauro Carvalho Chehab
15a04d4e76 docs-rst: auto-generate PDF image files
The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:59 -07:00
Markus Heiser
0af205ea6c Documentation/sphinx: fix make SPHINXDIRS="dirs" pdfdocs for more than one dir
Add missing semicolon to fix pdf build with more than one SPHINXDIRS
directory specified. For example make SPHINXDIRS="gpu media" pdfdocs.

Fixes: cd21379b16 ("doc-rst: generic way to build PDF of sub-folders")
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03 12:36:56 +02:00
Jani Nikula
eaed1b25a7 Documentation/sphinx: change pdflatex interaction mode to batchmode
Radically reduce the noise on stdout. The full build logs will still be
available under Documentatio/output/latex/*.log.

Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03 12:36:30 +02:00
Jani Nikula
c855696672 Documentation/sphinx: remove superfluous trailing ; from quiet_cmd_sphinx
With the unnecessary ; removed, the terminal URL detection also works
better.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03 12:35:45 +02:00
Jani Nikula
207fc55bc3 Documentation/sphinx: make it possible to build latexdocs without pdflatex
Building latexdocs doesn't actually require $(PDFLATEX). Move the checks
for it to the pdfdocs target which does require it, and specifically
outside of the target in order to not depend on latexdocs when we can't
build pdfdocs anyway.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03 12:35:29 +02:00
Jani Nikula
1171a28bac Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS
Refer to xelatex and latex options via variables. This allows the user
to override the pdflatex and latex options to use on the make command
line for experimenting. As a side effect, this makes the makefile a bit
tidier.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03 12:34:49 +02:00
Markus Heiser
cd21379b16 doc-rst: generic way to build PDF of sub-folders
This extends the method to build only sub-folders to the targets
"latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
required, where the latex_documents of the sub-folder are
defined. E.g. to build only gpu's PDF add the following to the
Documentation/gpu/conf.py::

  +latex_documents = [
  +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
  +     "The kernel development community", "manual"),
  +]

and run:

  make SPHINXDIRS=gpu pdfdocs

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:49:23 -06:00
Mauro Carvalho Chehab
d565127d12 docs-rst: add support for LaTeX output
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:26:17 -06:00
Mauro Carvalho Chehab
8b8bbf8fe5 docs-rst: Don't go to interactive mode on errors
When building for LaTeX, it stops and enters into interactive
mode on errors. Don't do that, as there are some non-fatal errors
on media books when using Sphinx 1.4.x that we don't know how fix
yet.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:42:24 -06:00
Mauro Carvalho Chehab
a682ec4ba1 docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
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>
2016-08-18 16:41:52 -06:00
Mauro Carvalho Chehab
16dbe8042e docs-rst: fix a breakage when building PDF documents
changeset 606b9ac81a ("doc-rst: generic way to build only sphinx
sub-folders") accidentally broke PDF generation by adding an extra
")". Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:41:20 -06:00
Markus Heiser
606b9ac81a doc-rst: generic way to build only sphinx sub-folders
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>
2016-08-14 11:51:51 -06:00
Jani Nikula
f907ba9307 Documentation: switch to pdflatex for pdf generation
Looks like rst2pdf is not robust enough, especially for large documents.

Use recursive make on the Sphinx generated makefile to convert latex to
pdf. The ugly detail is that pdf is generated into
Documentation/output/latex.

Unfortunately, the pdflatex build generates huge amounts of build log
noise, and also fails in the end. We'll fix that next.

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>
2016-08-12 15:25:19 -06:00
Jani Nikula
609afe6b49 Documentation/sphinx: build the media intermediate rst files for all outputs
This is a stopgap measure to allow building outputs other than html.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-12 15:24:25 -06:00
Linus Torvalds
52ddb7e9dd Three fixes for the docs build, including removing an annoying warning on
"make help" if sphinx isn't present.
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJXo8sIAAoJEI3ONVYwIuV6po0P/0ZZo+YF0GrPvOHr7uuUqAND
 0+4WRfSsT74z5Rn/W3apeX6CM7IGBMSR2zM89E2nWmbE2Uo7bIbrwj6C+Y6gMMfd
 aws0Xi9899Jr6hVkeFVZ9foze+M2yc3tE1vFBby035uW3Zwyz2XHzaU/9vyLOLkJ
 c7jhqCWebqFEqOSWtw2FZYegt2oHSjUsQgGCh3kk2pCU+DzLHntwbblJLeMuTy+h
 zPVxTTBcBkUZcIjpkSvhqc/oCLCiWKLElmwxPBwfpNU9UlE0rol2Lx1eLClxadFl
 QVlb1UAIjPcLnHQoM8dL9NR0tkfGopIDuNCL26GU5ie9N4zurOj5a6hj+G5mZKLB
 tsMqIw+N7ig5FnaQhaCx3oN/VMZ0djxURu9XvKsHBmOCd2Bp8SDoqpCkTwCqCxcN
 DVdUjpS1WUT9w2A1jhH32mx+23eRwJa5oaTFpM3Y0z7Bl9N40ScY2WJcgBKWqHgx
 LRROJAzNOPojbBkwTDNsRValwgtutCcqaRw5mNQTp3YjjmltmqylCvJH3AST+z5r
 CmMDO96O3rUGsCZYoBhxafC2FUUh5RkUwQq/Cy8nrioMookE3Yd5A9DN6wWQ2pTt
 tev/z6s3ov8dygeF6u3noOHCa8GPUpSHO62FyHUKYnn6Tl8xh3x7rmUkUqrJZi5a
 dnXOZzp34eVhev5xDeDN
 =iD7L
 -----END PGP SIGNATURE-----

Merge tag 'doc-4.8-fixes' of git://git.lwn.net/linux

Pull documentation fixes from Jonathan Corbet:
 "Three fixes for the docs build, including removing an annoying warning
  on 'make help' if sphinx isn't present"

* tag 'doc-4.8-fixes' of git://git.lwn.net/linux:
  DocBook: use DOCBOOKS="" to ignore DocBooks instead of IGNORE_DOCBOOKS=1
  Documenation: update cgroup's document path
  Documentation/sphinx: do not warn about missing tools in 'make help'
2016-08-07 10:23:17 -04:00
Jani Nikula
d9a77fe243 Documentation/sphinx: do not warn about missing tools in 'make help'
Simply move the dochelp rule outside of the HAVE_SPHINX check,
overriding the .DEFAULT rule for HAVE_SPHINX=0.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Christian Kujau <lists@nerdbynature.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-03 15:41:31 -06:00
Mauro Carvalho Chehab
43f71d93a0 doc-rst: Remove the media docbook
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-28 20:08:19 -03:00
Mauro Carvalho Chehab
425efba235 Merge branch 'docs-next' of git://git.lwn.net/linux into devel/docs-next
* 'docs-next' of git://git.lwn.net/linux:
  doc-rst: add an option to ignore DocBooks when generating docs
  workqueue: Fix a typo in workqueue.txt
  Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
  Documentation/sphinx: skip build if user requested specific DOCBOOKS
  Documentation: add cleanmediadocs to the documentation targets
2016-07-15 07:33:47 -03:00
Mauro Carvalho Chehab
60c2820d0f doc_rst: rename the media Sphinx suff to Documentation/media
The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-08 11:59:40 -03:00
Markus Heiser
627e32df1a doc-rst: linux_tv/Makefile: Honor quiet make O=dir
To honor the:

  make O=dir [targets] Locate all output files in "dir"

* activate kernel-include directive
* export BUILDDIR=$(BUILDDIR)
* linux_tv: replace '.. include::' with '.. kernel-include:: $BUILDDIR/<foo.h.rst>'

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-08 09:31:05 -03:00
Mauro Carvalho Chehab
573720f07b doc-rst: linux_tv/Makefile: Honor quiet mode
Cleanup the Makefile and handle the V=1 flag and make it
to work when specifying an output directory with O=dir

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-08 09:31:03 -03:00
Mauro Carvalho Chehab
1ae6439538 doc-rst: auto-build the frontend.h.rst
This file is auto-generated with DocBook, from the uapi header.

Do the same with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07 06:36:45 -03:00
Jani Nikula
6387872c86 Documentation/sphinx: skip build if user requested specific DOCBOOKS
If the user requested specific DocBooks to be built using 'make
DOCBOOKS=foo.xml htmldocs', assume no Sphinx build is desired. This
check is transitional, and can be removed once we drop the DocBook
build.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Fixes: 22cba31bae ("Documentation/sphinx: add basic working Sphinx configuration and build")
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-01 16:16:07 -06:00
Jani Nikula
a569bf69f0 Documentation: add cleanmediadocs to the documentation targets
This was broken when updating the documentation targets for the Sphinx
build, and moving from %docs target pattern to explicitly listed
targets.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Fixes: 22cba31bae ("Documentation/sphinx: add basic working Sphinx configuration and build")
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-01 16:15:31 -06:00
Jani Nikula
ebc88ef05c Documentation: add top level 'make help' output for Sphinx
While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-23 15:11:51 +03:00
Jani Nikula
c13ce448c8 Documentation/sphinx: set version and release properly
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>
2016-05-30 13:38:53 +03:00
Jani Nikula
24dcdeb28b Documentation/sphinx: configure the kernel-doc extension
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>
2016-05-30 13:38:52 +03:00
Jani Nikula
22cba31bae Documentation/sphinx: add basic working Sphinx configuration and build
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>
2016-05-30 13:38:51 +03:00