aboutsummaryrefslogtreecommitdiff
path: root/Documentation/sphinx
AgeCommit message (Collapse)Author
2020-06-08Replace HTTP links with HTTPS ones: documentationAlexander A. Klimov
Rationale: Reduces attack surface on kernel devs opening the links for MITM as HTTPS traffic is much harder to manipulate. Deterministic algorithm: For each file: For each line: If doesn't contain `\bxmlns\b`: For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`: If both the HTTP and HTTPS versions return 200 OK and serve the same content: Replace HTTP with HTTPS. Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de> Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-04-20docs: update recommended Sphinx version to 2.4.4Mauro Carvalho Chehab
There are some docs that have nested tables. While this was always part of the spec, only Sphinx version 2.4.x can translate it to LaTeX. In other words, if someone is using a Sphinx version < 2.4, the LaTeX and PDF output won't work for some of the docs. So, it seems that it is time to raise the bar again for the recommented version. The Sphinx check script is already smart enough to keep working, with older versions, warning the users that an upgrade is recommended (and explaining how): Sphinx version 1.7.9 Warning: It is recommended at least Sphinx version 2.4.4. Detected OS: Fedora release 31 (Thirty One). To upgrade Sphinx, use: /usr/bin/virtualenv sphinx_2.4.4 . sphinx_2.4.4/bin/activate pip install -r ./Documentation/sphinx/requirements.txt Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/498f701c618f7d0cf5f0a37e5889ee926f7c8bf4.1586881715.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-02-25docs: Fix empty parallelism argumentKees Cook
When there was no parallelism (no top-level -j arg and a pre-1.7 sphinx-build), the argument passed would be empty ("") instead of just being missing, which would (understandably) badly confuse sphinx-build. Fix this by removing the quotes. Reported-by: Rafael J. Wysocki <rafael@kernel.org> Fixes: 51e46c7a4007 ("docs, parallelism: Rearrange how jobserver reservations are made") Cc: stable@vger.kernel.org # v5.5 only Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-01-24docs: Keep up with the location of NoUriJonathan Corbet
Sphinx 2.1 moved sphinx.environment.NoUri into sphinx.errors; that produced this warning in the docs build: /usr/lib/python3.7/site-packages/sphinx/registry.py:473: RemovedInSphinx30Warning: sphinx.environment.NoUri is deprecated. Grab NoUri from the right place and make the warning go away. That symbol was only added to sphinx.errors in 2.1, so we must still import it from the old location when running in older versions. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-11-22docs, parallelism: Rearrange how jobserver reservations are madeKees Cook
Rasmus correctly observed that the existing jobserver reservation only worked if no other build targets were specified. The correct approach is to hold the jobserver slots until sphinx has finished. To fix this, the following changes are made: - refactor (and rename) scripts/jobserver-exec to set an environment variable for the maximally reserved jobserver slots and exec a child, to release the slots on exit. - create Documentation/scripts/parallel-wrapper.sh which examines both $PARALLELISM and the detected "-jauto" logic from Documentation/Makefile to decide sphinx's final -j argument. - chain these together in Documentation/Makefile Suggested-by: Rasmus Villemoes <linux@rasmusvillemoes.dk> Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk Signed-off-by: Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-11-07kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'Changbin Du
The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated. Signed-off-by: Changbin Du <changbin.du@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-02doc-rst: Programmatically render MAINTAINERS into ReSTKees Cook
In order to have the MAINTAINERS file visible in the rendered ReST output, this makes some small changes to the existing MAINTAINERS file to allow for better machine processing, and adds a new Sphinx directive "maintainers-include" to perform the rendering. Features include: - Per-subsystem reference links: subsystem maintainer entries can be trivially linked to both internally and external. For example: https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing - Internally referenced .rst files are linked so they can be followed when browsing the resulting rendering. This allows, for example, the future addition of maintainer profiles to be automatically linked. - Field name expansion: instead of the short fields (e.g. "M", "F", "K"), use the indicated inline "full names" for the fields (which are marked with "*"s in MAINTAINERS) so that a rendered subsystem entry is more human readable. Email lists are additionally comma-separated. For example: SECURE COMPUTING Mail: Kees Cook <keescook@chromium.org> Reviewer: Andy Lutomirski <luto@amacapital.net>, Will Drewry <wad@chromium.org> SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp Status: Supported Files: kernel/seccomp.c include/uapi/linux/seccomp.h include/linux/seccomp.h tools/testing/selftests/seccomp/* tools/testing/selftests/kselftest_harness.h userspace-api/seccomp_filter Content regex: \bsecure_computing \bTIF_SECCOMP\b Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-08-12Documentation: sphinx: Don't parse socket() as identifier referenceJonathan Neuschäfer
With the introduction of Documentation/sphinx/automarkup.py, socket() is parsed as a reference to the in-kernel definition of socket. Sphinx then decides that struct socket is a good match, which is usually not intended, when the syscall is meant instead. This was observed in Documentation/networking/af_xdp.rst. Prevent socket() from being misinterpreted by adding it to the Skipfuncs list in automarkup.py. Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-08-12Documentation: sphinx: Add missing comma to list of stringsJonathan Neuschäfer
In Python, like in C, when a comma is omitted in a list of strings, the two strings around the missing comma are concatenated. Cc: stable@vger.kernel.org # v5.2 only Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-07-19docs: load_config.py: ensure subdirs end with "/"Mauro Carvalho Chehab
The logic with seeks for a subdir passed via SPHINXDIRS is incomplete: if one uses something like: make SPHINXDIRS=arm pdfdocs It will find both "arm" and "arm64" directories. Worse than that, it will convert "arm64/index" to "4/index". Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17docs: load_config.py: avoid needing a conf.py just due to LaTeX docsMauro Carvalho Chehab
Right now, for every directory that we need to have LaTeX output, a conf.py file is required. That causes an extra overhead and it is actually a hack, as the latex_documents line there are usually a copy of the ones that are there already at the main conf.py. So, instead, re-use the global latex_documents var, just adjusting the path to be relative ones. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-08docs: automarkup.py: ignore exceptions when seeking for xrefsMauro Carvalho Chehab
When using the automarkup extension with: make pdfdocs without passing an specific book, the code will raise an exception: File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 86, in auto_markup node.parent.replace(node, markup_funcs(name, app, node)) File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 59, in markup_funcs 'function', target, pxref, lit_text) File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/domains/c.py", line 308, in resolve_xref contnode, target) File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/util/nodes.py", line 450, in make_refnode '#' + targetid) File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py", line 159, in get_relative_uri return self.get_target_uri(to, typ) File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py", line 152, in get_target_uri raise NoUri sphinx.environment.NoUri This happens because not all references will belong to a single PDF/LaTeX document. Better to just ignore those than breaking Sphinx build. Fixes: d74b0d31ddde ("Docs: An initial automarkup extension for sphinx") Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> [jc: Narrowed the "except" and tweaked the comment] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26Docs: An initial automarkup extension for sphinxJonathan Corbet
Rather than fill our text files with :c:func:`function()` syntax, just do the markup via a hook into the sphinx build process. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-30docs: requirements.txt: recommend Sphinx 1.7.9Mauro Carvalho Chehab
As discussed at the linux-doc ML, while we'll still support version 1.3, it is time to recommend a more modern version. So, let's switch the minimal requirements to Sphinx 1.7.9, as it has the "-jauto" flag, with makes a lot faster when building documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-29docs: cdomain.py: get rid of a warning since version 1.8Mauro Carvalho Chehab
There's a new warning about a deprecation function. Add a logic at cdomain.py to avoid that. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-23doc: Cope with the deprecation of AutoReporterJonathan Corbet
AutoReporter is going away; recent versions of sphinx emit a warning like: Documentation/sphinx/kerneldoc.py:125: RemovedInSphinx20Warning: AutodocReporter is now deprecated. Use sphinx.util.docutils.switch_source_input() instead. Make the switch. But switch_source_input() only showed up in 1.7, so we have to do ugly version checks to keep things working in older versions. Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-23doc: Cope with Sphinx logging deprecationsJonathan Corbet
Recent versions of sphinx will emit messages like: Documentation/sphinx/kerneldoc.py:103: RemovedInSphinx20Warning: app.warning() is now deprecated. Use sphinx.util.logging instead. Switch to sphinx.util.logging to make this unsightly message go away. Alas, that interface was only added in version 1.6, so we have to add a version check to keep things working with older sphinxes. Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-30Documentation/sphinx: allow "functions" with no parametersMike Rapoport
When kernel-doc:: specified in .rst document without explicit directives, it outputs both comment and DOC: sections. If a DOC: section was explicitly included in the same document it will be duplicated. For example, the output generated for Documentation/core-api/idr.rst [1] has "IDA description" in the "IDA usage" section and in the middle of the API reference. This patch enables using "functions" directive without parameters to output all the documentation excluding DOC: sections. [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com> Acked-by: Matthew Wilcox <willy@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-26doc:sphinx: fix parse-header descriptionFederico Vaga
The description speaks about the option ``--man`` but it does not exist. Instead, there is the option ``--usage`` $ ./Documentation/sphinx/parse-headers.pl --man Unknown option: man Usage: parse_headers.pl [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] Where <options> can be: --debug, --help or --man. Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-06-15Documentation: rstFlatTable.py: fix a broken referenceMauro Carvalho Chehab
The old HOWTO was removed a long time ago. The flat table version is not metioned elsewhere, so just get rid of the text. Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Jonathan Corbet <corbet@lwn.net>
2018-05-04MAINTAINERS & files: Canonize the e-mails I use at filesMauro Carvalho Chehab
From now on, I'll start using my @kernel.org as my development e-mail. As such, let's remove the entries that point to the old mchehab@s-opensource.com at MAINTAINERS file. For the files written with a copyright with mchehab@s-opensource, let's keep Samsung on their names, using mchehab+samsung@kernel.org, in order to keep pointing to my employer, with sponsors the work. For the files written before I join Samsung (on July, 4 2013), let's just use mchehab@kernel.org. For bug reports, we can simply point to just kernel.org, as this will reach my mchehab+samsung inbox anyway. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Brian Warner <brian.warner@samsung.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2018-03-09Documentation/sphinx: Fix Directive import errorMatthew Wilcox
Sphinx 1.7 removed sphinx.util.compat.Directive so people who have upgraded cannot build the documentation. Switch to docutils.parsers.rst.Directive which has been available since docutils 0.5 released in 2009. Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694 Co-developed-by: Takashi Iwai <tiwai@suse.de> Acked-by: Jani Nikula <jani.nikula@intel.com> Cc: stable@vger.kernel.org Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-01-17linux-next: docs-rst: Fix typos in kfigure.pyMasanari Iida
This patch fixes some spelling typos found in kfigure.py Signed-off-by: Masanari Iida <standby24x7@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-31Documentation/sphinx: fix kernel-doc decode for non-utf-8 localeJani Nikula
On python3, Popen() universal_newlines=True converts the subprocess stdout to unicode text using a codec based on user preferences. Given LANG indicating ascii and utf-8 stdout from the subprocess, you'd get: WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't decode byte 0xe2 in position 6368: ordinal not in range(128) Fix this by dropping universal_newlines=True and replacing the implicit LANG specific decode with an explicit utf-8 decode. This also gets rid of the annoying conditional code for python 2 vs. 3. Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on python3") Reference: http://mid.mail-archive.com/54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org Reported-and-tested-by: Randy Dunlap <rdunlap@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-07-23sphinx-pre-install: use a requirements fileMauro Carvalho Chehab
Instead of using 3 commands to install a virtualenv, use a single one, reading the requirements from this file: Documentation/sphinx/requirements.txt Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-06-23Docs: clean up some DocBook loose endsJonathan Corbet
There were a few bits and pieces left over from the now-disused DocBook toolchain; git rid of them. Reported-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-05-16docs-rst: get rid of Documentation/sphinx/tmplcvt scriptMauro Carvalho Chehab
As everything was converted to ReST, we don't need this script anymore. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-04-11tmplcvt: make the tool more robustMauro Carvalho Chehab
Currently, the script just assumes to be called at Documentation/sphinx/. Change it to work on any directory, and make it abort if something gets wrong. Also, be sure that both parameters are specified. That should avoid troubles like this: $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl sed: couldn't open file convert_template.sed: No such file or directory Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-31Use sphinx.version_info directly instead of parsingRémy Léone
Using the development version of sphinx caused the parsing of the version to fail. Signed-off-by: Rémy Léone <remy.leone@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-03-09docs-rst: automatically convert Graphviz and SVG imagesMarkus Heiser
This patch brings scalable figure, image handling and a concept to embed *render* markups: * DOT (http://www.graphviz.org) * SVG For image handling use the 'image' replacement:: .. kernel-image:: svg_image.svg :alt: simple SVG image For figure handling use the 'figure' replacement:: .. kernel-figure:: svg_image.svg :alt: simple SVG image SVG image example Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the *render* directive.:: .. kernel-render:: DOT :alt: foobar digraph :caption: Embedded **DOT** (Graphviz) code. digraph foo { "bar" -> "baz"; } The *render* directive is a concept to integrate *render* markups and languages, yet supported markups: * DOT: render embedded Graphviz's **DOT** * SVG: render embedded Scalable Vector Graphics (**SVG**) Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5) Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6) Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-18docs: sphinx-extensions: make rstFlatTable work with docutils 0.13Dmitry Shachnev
In docutils 0.13, the return type of get_column_widths method of the Table directive has changed [1], which breaks our flat-table directive and leads to a TypeError when trying to build the docs [2]. This patch adds support for the new return type, while keeping support for older docutils versions too. [1] https://sourceforge.net/p/docutils/patches/120/ [2] https://sourceforge.net/p/docutils/bugs/303/ Signed-off-by: Dmitry Shachnev <mitya57@debian.org> Cc: <stable@vger.kernel.org> # 4.8.x- Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30docs-rst: parse-headers.pl: cleanup the documentationMauro Carvalho Chehab
Keeping both rst and in-file documentation in sync can be harsh. So, simplify the script's internal documntation to a bare minimum, and add a mention to the ReST file with its full documentation. This way, a quick help is still available at the command line, while the complete one is maintained at the ReST format. As we won't be using pad2rst anymore, do a cleanup at the ReST file. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19parse-headers.pl: add documentation for this scriptMauro Carvalho Chehab
Provide a man page for parse-headers.pl, describing how to use it. The documentation on ReST format was generated via pod2rst: http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-10-19Documentation/sphinx: rename kernel-doc.py to kerneldoc.pyJani Nikula
Python module names should not have hyphens per [PEP 8]. Drop the hyphen from kernel-doc.py. The extension directive remains unchanged. [PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names Reported-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-19Merge tag 'docs-next' of git://git.lwn.net/linux.git into patchworkMauro Carvalho Chehab
Merge back from docs-next in order to get the cdomain extension. With such extension, the number of warnings when building docs in nitpick mode reduced from 22 to 2 warnings. * docs-next/docs-next: docs/driver-model: fix typo DMA-API-HOWTO: <asm/generic/scatterlist.h> is no more doc-rst:c-domain: function-like macros arguments doc-rst:c-domain: fix sphinx version incompatibility Documentation/filesystems: Fixed typo docs: Don't format internal MPT docs docs: split up serial-interfaces.rst docs: Pull the HSI documentation together docs: Special-case function-pointer parameters in kernel-doc docs: make kernel-doc handle varargs properly x86: fix memory ranges in mm documentation documentation/scsi: Remove nodisconnect parameter doc: ioctl: Add some clarifications to botching-up-ioctls docs: split up the driver book Docs: sphinxify device-drivers.tmpl
2016-09-16doc-rst:c-domain: function-like macros argumentsMarkus Heiser
Handle signatures of function-like macros well. Don't try to deduce arguments types of function-like macros. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16doc-rst:c-domain: fix sphinx version incompatibilityMarkus Heiser
The self.indexnode's tuple has changed in sphinx version 1.4, from a former 4 element tuple to a 5 element tuple. https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-09[media] docs-rst: parse-headers.pl: use the C domain for cross-referencesMauro Carvalho Chehab
Instead of keep using the normal reference, move to the C domain ones. Using C domains everywhere will allow cross-references between kAPI and uAPI docs. Acked-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-09[media] docs-rst: parse-headers.pl: make debug a command line optionMauro Carvalho Chehab
Add a parser for the --debug option, in order to allow seeing what the parser is doing. Acked-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-01docs: sphinx-extensions: add metadata parallel-safeMarkus Heiser
The setup() function of a Sphinx-extension can return a dictionary. This is treated by Sphinx as metadata of the extension [1]. With metadata "parallel_read_safe = True" a extension is marked as save for "parallel reading of source". This is needed if you want build in parallel with N processes. E.g.: make SPHINXOPTS=-j4 htmldocs will no longer log warnings like: WARNING: the foobar extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit. Add metadata to extensions: * kernel-doc * flat-table * kernel-include [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22doc-rst: moved *duplicate* warnings to nitpicky modeMarkus Heiser
Moved the *duplicate C object description* warnings for function declarations in the nitpicky mode. In nitpick mode, you can suppress those warnings (e.g. ioctl) with:: nitpicky = True nitpick_ignore = [ ("c:func", "ioctl"), ] See Sphinx documentation for the config values for ``nitpick`` and ``nitpick_ignore`` [1]. With this change all the ".. cpp:function:: int ioctl(..)" descriptions (found in the media book) can be migrated to ".. c:function:: int ioctl(..)", without getting any warnings. E.g.:: .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) .. c:function:: int ioctl( int fd, int request, struct cec_event *argp ) The main effect, is that we get those *CPP-types* back into Sphinx's C- namespace and we need no longer to distinguish between c/cpp references, when we refer a function like the ioctl. [1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22doc-rst:c-domain: ref-name of a function declarationMarkus Heiser
Add option 'name' to the "c:function:" directive. With option 'name' the ref-name of a function can be modified. E.g.:: .. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUS The func-name (e.g. ioctl) remains in the output but the ref-name changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:: :c:func:`VIDIOC_LOG_STATUS` Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22doc-rst: add boilerplate to customize c-domainMarkus Heiser
Add a sphinx-extension to customize the sphinx c-domain. No functional changes right yet, just the boilerplate code. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> [ jc: coding-style tweak ] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18docs-rst: parse-heraders.pl: escape LaTeX charactersMauro Carvalho Chehab
Let's escape the LaTeX characters, to avoid troubles when outputing them. 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 Heiser
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-07-23Merge branch 'docs-next' of git://git.lwn.net/linux into topic/docs-nextMauro Carvalho Chehab
* 'docs-next' of git://git.lwn.net/linux: doc-rst: kernel-doc: fix handling of address_space tags Revert "doc/sphinx: Enable keep_warnings" doc-rst: kernel-doc directive, fix state machine reporter docs: deprecate kernel-doc-nano-HOWTO.txt doc/sphinx: Enable keep_warnings Documentation: add watermark_scale_factor to the list of vm systcl file kernel-doc: Fix up warning output docs: Get rid of some kernel-documentation warnings
2016-07-20doc-rst: kernel-doc directive, fix state machine reporterMarkus Heiser
Add a reporter replacement that assigns the correct source name and line number to a system message, as recorded in a ViewList. [1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-07-09doc-rst: parse-headers: remove trailing spacesMauro Carvalho Chehab
The function that replace references add a "\ " at the end of references, to avoid the ReST markup parser to not identify them as references. That works fine except for the end of lines, as a sequence of { '\', ' ', '\n' } characters makes Sphinx to ignore the end of line. So, strip those escape/spaces at the end of lines. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-08doc-rst: add kernel-include directiveMarkus Heiser
The kernel-include directive is needed to include the auto generated rst content from a build (pre-) process. E.g. the linux_tv Makefile generates intermediate reST-files from header files. Since there is a O= option: make O=dir [targets] Locate all output files in "dir" We need to include intermediate reST files from arbitrary (O=/tmp/foo) locations: The 'kernel-include' reST-directive is a replacement for the 'include' directive. The 'kernel-include' directive expand environment variables in the path name and allows to include files from arbitrary locations. .. hint:: Including files from arbitrary locations (e.g. from '/etc') is a security risk for builders. This is why the 'include' directive from docutils *prohibit* pathnames pointing to locations *above* the filesystem tree where the reST document with the include directive is placed. Substrings of the form $name or ${name} are replaced by the value of environment variable name. Malformed variable names and references to non-existing variables are left unchanged. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: parse-headers: don't do substituition referencesMauro Carvalho Chehab
Add one extra escape character to avoid those warnings: Documentation/linux_tv/videodev2.h.rst:6: WARNING: Inline substitution_reference start-string without end-string. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-16 01:24:13 +0000