summaryrefslogtreecommitdiffstats
path: root/Documentation/Makefile.sphinx
Commit message (Collapse)AuthorAgeFilesLines
* docs-rst: fix media cleandocs targetMauro Carvalho Chehab2016-11-301-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>
* docs-rst: auto-generate PDF image filesMauro Carvalho Chehab2016-11-161-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>
* Documentation/sphinx: fix make SPHINXDIRS="dirs" pdfdocs for more than one dirMarkus Heiser2016-11-031-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>
* Documentation/sphinx: change pdflatex interaction mode to batchmodeJani Nikula2016-11-031-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>
* Documentation/sphinx: remove superfluous trailing ; from quiet_cmd_sphinxJani Nikula2016-11-031-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>
* Documentation/sphinx: make it possible to build latexdocs without pdflatexJani Nikula2016-11-031-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>
* Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTSJani Nikula2016-11-031-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>
* doc-rst: generic way to build PDF of sub-foldersMarkus Heiser2016-09-011-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>
* docs-rst: add support for LaTeX outputMauro Carvalho Chehab2016-08-221-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>
* docs-rst: Don't go to interactive mode on errorsMauro Carvalho Chehab2016-08-181-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>
* docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF outputMauro Carvalho Chehab2016-08-181-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>
* docs-rst: fix a breakage when building PDF documentsMauro Carvalho Chehab2016-08-181-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>
* doc-rst: generic way to build only sphinx sub-foldersMarkus Heiser2016-08-141-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>
* Documentation: switch to pdflatex for pdf generationJani Nikula2016-08-121-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>
* Documentation/sphinx: build the media intermediate rst files for all outputsJani Nikula2016-08-121-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>
* Merge tag 'doc-4.8-fixes' of git://git.lwn.net/linuxLinus Torvalds2016-08-071-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'
| * Documentation/sphinx: do not warn about missing tools in 'make help'Jani Nikula2016-08-031-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>
* | doc-rst: Remove the media docbookMauro Carvalho Chehab2016-07-281-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>
* | Merge branch 'docs-next' of git://git.lwn.net/linux into devel/docs-nextMauro Carvalho Chehab2016-07-151-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
| * Documentation/sphinx: skip build if user requested specific DOCBOOKSJani Nikula2016-07-011-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>
| * Documentation: add cleanmediadocs to the documentation targetsJani Nikula2016-07-011-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>
* | doc_rst: rename the media Sphinx suff to Documentation/mediaMauro Carvalho Chehab2016-07-081-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>
* | doc-rst: linux_tv/Makefile: Honor quiet make O=dirMarkus Heiser2016-07-081-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>
* | doc-rst: linux_tv/Makefile: Honor quiet modeMauro Carvalho Chehab2016-07-081-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>
* | doc-rst: auto-build the frontend.h.rstMauro Carvalho Chehab2016-07-071-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>
* Documentation: add top level 'make help' output for SphinxJani Nikula2016-06-231-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>
* Documentation/sphinx: set version and release properlyJani Nikula2016-05-301-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>
* Documentation/sphinx: configure the kernel-doc extensionJani Nikula2016-05-301-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>
* Documentation/sphinx: add basic working Sphinx configuration and buildJani Nikula2016-05-301-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>
OpenPOWER on IntegriCloud