summaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx
AgeCommit message (Collapse)AuthorFilesLines
2018-06-30Documentation/sphinx: allow "functions" with no parametersMike Rapoport1-3/+7
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 Vaga1-1/+1
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 Chehab1-2/+0
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 Chehab1-2/+2
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 Wilcox1-2/+1
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 Iida1-3/+3
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 Nikula1-5/+3
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 Chehab1-0/+3
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 Corbet2-41/+0
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 Chehab1-28/+0
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 Chehab1-2/+11
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éone1-1/+1
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 Heiser1-0/+551
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 Shachnev1-0/+5
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 Chehab1-107/+9
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 Chehab1-13/+180
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 Nikula1-0/+0
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 Chehab1-3/+66
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 Heiser1-1/+54
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 Heiser1-2/+12
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 Chehab1-54/+59
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 Chehab1-4/+10
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 Heiser3-0/+21
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 Heiser1-0/+27
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 Heiser1-0/+31
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 Heiser1-0/+44
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 Chehab1-1/+1
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 Heiser1-0/+32
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 Chehab1-3/+9
* '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 Heiser1-3/+9
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 Chehab1-0/+2
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 Heiser1-0/+183
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 Chehab1-1/+1
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>
2016-07-07doc-rst: parse-headers: add an option to ignore enum symbolsMauro Carvalho Chehab1-0/+4
At videodev2.h, we have hundreds of symbols that don't currently have a reference yet. Let's ignore for how, while we don't improve those cross-refs. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: parse-headers: better handle comments at the source codeMauro Carvalho Chehab1-3/+14
We should not let comments to mangle with the symbols parsing. Unfortunately, videodev2.h has lots of those in the middle of enums and structs. So, we need to improve our parser to discard them. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: parse-headers: fix multiline typedef handlerMauro Carvalho Chehab1-3/+4
The typedef handler should do two things to be generic: 1) parse typedef enums; 2) accept both possible syntaxes: typedef struct foo { .. } foo_t; typedef struct { .. } foo_t; Unfortunately, this is needed to parse some legacy DVB files, like dvb/audio.h. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: parse-headers: better handle typedefsMauro Carvalho Chehab1-2/+7
When typedef is used on its multiline format, we need to also parse enum and struct in the same line. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: parse-headers: be more formal about the valid symbolsMauro Carvalho Chehab1-8/+8
Be more formal about the valid symbols that are expected by the parser, to match what c language expects. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: fix parsing comments and '{' on a separate lineMauro Carvalho Chehab1-6/+11
The dmx.h header has two things that causes the parser to break while handling enums: per-header enums and the '{' starts on a new line Both makes the parser to get lexical marks to be detected as if they were symbols. Fix it. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-dst: parse-headers: highlight deprecated commentsMauro Carvalho Chehab1-0/+2
When something is deprecated, highlight it, as we want it to be clearer to the reader. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: parse-headers: improve delimiters to detect symbolsMauro Carvalho Chehab1-13/+14
As we had to escape the symbols for the ReST markup to not do the wrong thing, the logic to discover start/end of strings are not trivial. Improve the end delimiter detection, in order to highlight more occurrences of the strings. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-07doc-rst: add parse-headers.pl scriptMauro Carvalho Chehab1-0/+290
This script parses a header file and converts it into a parsed-literal block, creating references for ioctls, defines, typedefs, enums and structs. It also allow an external file to modify the rules, in order to fix the expressions. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-06-30doc-rst: flat-table directive - initial implementationMarkus Heiser1-0/+365
Implements the reST flat-table directive. The ``flat-table`` is a double-stage list similar to the ``list-table`` with some additional features: * column-span: with the role ``cspan`` a cell can be extended through additional columns * row-span: with the role ``rspan`` a cell can be extended through additional rows * auto span rightmost cell of a table row over the missing cells on the right side of that table-row. With Option ``:fill-cells:`` this behavior can changed from *auto span* to *auto fill*, which automaticly inserts (empty) list tables The *list tables* formats are double stage lists. Compared to the ASCII-art they migth be less comfortable for readers of the text-files. Their advantage is, that they are easy to create/modify and that the diff of a modification is much more meaningfull, because it is limited to the modified content. The initial implementation was taken from the sphkerneldoc project [1] [1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> [jc: fixed typos and misspellings in the docs] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-10Documentation/sphinx: add support for specifying extra export filesJani Nikula1-2/+11
Let the user specify file patterns where to look for the EXPORT_SYMBOLs in addition to the file with kernel-doc comments. This is directly based on the -export-file FILE option added to kernel-doc in "kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs", but we extend that with globbing patterns in the Sphinx extension. The file patterns are added as options to the :export: and :internal: arguments of the kernel-doc directive. For example, to extract the documentation of exported functions from include/net/mac80211.h: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c Without the file pattern, no exported functions would be found, as the EXPORT_SYMBOLs are placed in the various source files under net/mac80211. The matched files are also added as dependencies on the document in Sphinx, as they may affect the output. This is one of the reasons to do the globbing in the Sphinx extension instead of in scripts/kernel-doc. The file pattern remains optional, and is not needed if the kernel-doc comments and EXPORT_SYMBOLs are placed in the source file passed in as the main argument to the kernel-doc directive. This is the most common case across the kernel source tree. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10Documentation/sphinx: use a more sensible string split in kernel-doc extensionJani Nikula1-1/+1
Using the default str.split doesn't return empty strings like the current version does. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-10Documentation/sphinx: remove unnecessary temporary variableJani Nikula1-2/+1
Leftover cruft. No functional changes. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-04doc/sphinx: Track line-number of starting blocksDaniel Vetter1-2/+15
Design is pretty simple: kernel-doc inserts breadcrumbs with line numbers, and sphinx picks them up. At first I went with a sphinx comment, but inserting those at random places seriously upsets the parser, and must be filtered. Hence why this version now uses "#define LINEO " since one of these ever escape into output it's pretty clear there is a bug. It seems to work well, and at least the 2-3 errors where sphinx complained about something that was not correct in kernel-doc text the line numbers matched up perfectly. v2: Instead of noodling around in the parser state machine, create a ViewList and parse it ourselves. This seems to be the recommended way, per Jani's suggestion. v3: - Split out ViewList pach. Splitting the kernel-doc changes from the sphinx ones isn't possible, since emitting the LINENO lines wreaks havoc with the rst formatting. We must filter them. - Improve the regex per Jani's suggestions, and compile it just once for speed. - Now that LINENO lines are eaten, also add them to function parameter descriptions. Much less content and offset than for in-line struct member descriptions, but still nice to know which exact continuation line upsets sphinx. - Simplify/clarify the line +/-1 business a bit. v4: Split out the scripts/kernel-doc changes and make line-numbers opt-in, as suggested by Jani. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-03doc/sphinx: Stop touching state_machine internalsDaniel Vetter1-2/+9
Instead of just forcefully inserting our kernel-doc input and letting the state machine stumble over it the recommended way is to create ViewList, parse that and then return the list of parsed nodes. Suggested by Jani. Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-01doc/sphinx: Pass right filename as sourceDaniel Vetter1-1/+1
With this error output becomes almost readable. The line numbers are still totally bonghits, but that's a lot harder to pull out of kerneldoc. We'd essentially have to insert some special markers in the kernel-doc output, split the output along these markers and then insert each block separately using state_machine.insert_input(block, source, first_line) Cc: Jani Nikula <jani.nikula@intel.com> Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-06-01Documentation/sphinx: fix kernel-doc extension on python3Jani Nikula1-2/+7
Reconcile differences between python2 and python3 on dealing with stdout, stderr from Popen. This fixes "name 'unicode' is not defined" errors on python3. We'll need to try to keep the extension working on both python-sphinx and python3-sphinx so we don't need two copies. Reported-and-tested-by: Marius Vlad <marius.c.vlad@intel.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-26 23:00:03 +0000