Commit Graph

22 Commits

Author SHA1 Message Date
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