30 Jun, 2018
1 commit
-
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
Acked-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet
26 Jun, 2018
1 commit
-
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 [] []Where can be: --debug, --help or --man.
Signed-off-by: Federico Vaga
Signed-off-by: Jonathan Corbet
16 Jun, 2018
1 commit
-
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
Acked-by: Jonathan Corbet
04 May, 2018
1 commit
-
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
Signed-off-by: Brian Warner
Signed-off-by: Mauro Carvalho Chehab
10 Mar, 2018
1 commit
-
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
Acked-by: Jani Nikula
Cc: stable@vger.kernel.org
Signed-off-by: Matthew Wilcox
Signed-off-by: Jonathan Corbet
18 Jan, 2018
1 commit
-
This patch fixes some spelling typos found in kfigure.py
Signed-off-by: Masanari Iida
Signed-off-by: Jonathan Corbet
01 Sep, 2017
1 commit
-
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
Cc: Jonathan Corbet
Cc: Mauro Carvalho Chehab
Signed-off-by: Jani Nikula
Signed-off-by: Jonathan Corbet
24 Jul, 2017
1 commit
-
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
Signed-off-by: Jonathan Corbet
24 Jun, 2017
1 commit
-
There were a few bits and pieces left over from the now-disused DocBook
toolchain; git rid of them.Reported-by: Markus Heiser
Signed-off-by: Jonathan Corbet
16 May, 2017
1 commit
-
As everything was converted to ReST, we don't need this
script anymore.Signed-off-by: Mauro Carvalho Chehab
12 Apr, 2017
1 commit
-
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 directorySigned-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
31 Mar, 2017
1 commit
-
Using the development version of sphinx caused the parsing of the
version to fail.Signed-off-by: Rémy Léone
Signed-off-by: Jonathan Corbet
09 Mar, 2017
1 commit
-
This patch brings scalable figure, image handling and a concept to
embed *render* markups:* DOT (http://www.graphviz.org)
* SVGFor image handling use the 'image' replacement::
.. kernel-image:: svg_image.svg
:alt: simple SVG imageFor figure handling use the 'figure' replacement::
.. kernel-figure:: svg_image.svg
:alt: simple SVG imageSVG 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
Cc: Laurent Pinchart
Tested-by: Mauro Carvalho Chehab
Tested-by: Daniel Vetter
Signed-off-by: Daniel Vetter (v2 - v5)
Signed-off-by: Markus Heiser (v1, v6)
Signed-off-by: Jonathan Corbet
19 Dec, 2016
1 commit
-
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
Cc: # 4.8.x-
Signed-off-by: Jonathan Corbet
01 Dec, 2016
1 commit
-
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
Signed-off-by: Jonathan Corbet
20 Nov, 2016
1 commit
-
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/pod2rstSigned-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
20 Oct, 2016
1 commit
-
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
Signed-off-by: Jani Nikula
Signed-off-by: Jonathan Corbet
20 Sep, 2016
1 commit
-
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: 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
16 Sep, 2016
2 commits
-
Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
09 Sep, 2016
2 commits
-
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
Signed-off-by: Mauro Carvalho Chehab -
Add a parser for the --debug option, in order to allow
seeing what the parser is doing.Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
01 Sep, 2016
1 commit
-
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
Tested-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
23 Aug, 2016
3 commits
-
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
Signed-off-by: Jonathan Corbet -
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_STATUSThe 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
Signed-off-by: Jonathan Corbet -
Add a sphinx-extension to customize the sphinx c-domain. No functional
changes right yet, just the boilerplate code.Signed-off-by: Markus Heiser
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet
19 Aug, 2016
1 commit
-
Let's escape the LaTeX characters, to avoid troubles when
outputing them.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
15 Aug, 2016
1 commit
-
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_CONFFolders 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
Signed-off-by: Jonathan Corbet
23 Jul, 2016
1 commit
-
* '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
21 Jul, 2016
1 commit
-
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
Tested-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
09 Jul, 2016
1 commit
-
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
08 Jul, 2016
4 commits
-
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
Signed-off-by: Mauro 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
-
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
-
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
07 Jul, 2016
5 commits
-
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
-
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
-
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
-
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 lineBoth makes the parser to get lexical marks to be detected
as if they were symbols.Fix it.
Signed-off-by: Mauro Carvalho Chehab
-
When something is deprecated, highlight it, as we want it
to be clearer to the reader.Signed-off-by: Mauro Carvalho Chehab