summaryrefslogtreecommitdiff
path: root/Documentation/Makefile.sphinx
AgeCommit message (Collapse)AuthorFilesLines
2017-02-16Add a target to check broken external links in the DocumentationRémy Léone1-0/+4
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-13Documentation: make Makefile.sphinx no-ops quieterJim Davis1-0/+4
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-06Merge branch 'ben' into docs-nextJonathan Corbet1-8/+8
Ben writes: "This series fixes some bugs I found in the new doc build system."
2017-02-06doc-rst: Fix recursive make invocation from macrosBen Hutchings1-4/+4
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: 609afe6b49ef ("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-06doc-rst: Break shell command sequences on failureBen Hutchings1-4/+4
As $(SHELL) doesn't include the -e option, any loop or other sequence needs to include explicit checks for failing commands. Fixes: 609afe6b49ef ("Documentation/sphinx: build the media intermediate ...") Fixes: 606b9ac81a63 ("doc-rst: generic way to build only sphinx sub-folders") Fixes: cd21379b1698 ("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-01Documentation/sphinx: make targets independent of Sphinx work for HAVE_SPHINX=0Jani Nikula1-2/+5
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-01doc-rst: fixed cleandoc target when used with O=dirMarkus Heiser1-1/+1
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:100: recipe for target 'cleandocs' failed Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-02-01Documentation/sphinx: prevent generation of .pyc files in the source treeJani Nikula1-0/+1
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>
2016-12-01docs-rst: fix media cleandocs targetMauro Carvalho Chehab1-1/+1
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-17docs-rst: auto-generate PDF image filesMauro Carvalho Chehab1-1/+2
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-03Documentation/sphinx: fix make SPHINXDIRS="dirs" pdfdocs for more than one dirMarkus Heiser1-1/+1
Add missing semicolon to fix pdf build with more than one SPHINXDIRS directory specified. For example make SPHINXDIRS="gpu media" pdfdocs. Fixes: cd21379b1698 ("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-03Documentation/sphinx: change pdflatex interaction mode to batchmodeJani Nikula1-1/+1
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-03Documentation/sphinx: remove superfluous trailing ; from quiet_cmd_sphinxJani Nikula1-1/+1
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-03Documentation/sphinx: make it possible to build latexdocs without pdflatexJani Nikula1-3/+5
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-03Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTSJani Nikula1-3/+6
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-09-01doc-rst: generic way to build PDF of sub-foldersMarkus Heiser1-2/+2
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-08-23docs-rst: add support for LaTeX outputMauro Carvalho Chehab1-1/+6
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-19docs-rst: Don't go to interactive mode on errorsMauro Carvalho Chehab1-1/+1
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-19docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF outputMauro Carvalho Chehab1-3/+3
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-19docs-rst: fix a breakage when building PDF documentsMauro Carvalho Chehab1-1/+1
changeset 606b9ac81a63 ("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-14doc-rst: generic way to build only sphinx sub-foldersMarkus Heiser1-7/+36
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-13Documentation: switch to pdflatex for pdf generationJani Nikula1-7/+8
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-13Documentation/sphinx: build the media intermediate rst files for all outputsJani Nikula1-2/+1
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-07Merge tag 'doc-4.8-fixes' of git://git.lwn.net/linuxLinus Torvalds1-2/+2
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-04Documentation/sphinx: do not warn about missing tools in 'make help'Jani Nikula1-2/+2
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-07-29doc-rst: Remove the media docbookMauro Carvalho Chehab1-1/+0
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-15Merge branch 'docs-next' of git://git.lwn.net/linux into devel/docs-nextMauro Carvalho Chehab1-0/+7
* '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-08doc_rst: rename the media Sphinx suff to Documentation/mediaMauro Carvalho Chehab1-1/+1
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-08doc-rst: linux_tv/Makefile: Honor quiet make O=dirMarkus Heiser1-2/+2
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-08doc-rst: linux_tv/Makefile: Honor quiet modeMauro Carvalho Chehab1-1/+1
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-07doc-rst: auto-build the frontend.h.rstMauro Carvalho Chehab1-0/+1
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-02Documentation/sphinx: skip build if user requested specific DOCBOOKSJani Nikula1-0/+6
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: 22cba31bae9d ("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-02Documentation: add cleanmediadocs to the documentation targetsJani Nikula1-0/+1
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: 22cba31bae9d ("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-06-23Documentation: add top level 'make help' output for SphinxJani Nikula1-0/+8
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-05-30Documentation/sphinx: set version and release properlyJani Nikula1-1/+1
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-30Documentation/sphinx: configure the kernel-doc extensionJani Nikula1-1/+3
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-30Documentation/sphinx: add basic working Sphinx configuration and buildJani Nikula1-0/+61
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>