13 Aug, 2019
2 commits
-
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
Reviewed-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
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
Reviewed-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
19 Jul, 2019
1 commit
-
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
17 Jul, 2019
1 commit
-
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
09 Jul, 2019
1 commit
-
When using the automarkup extension with:
make pdfdocswithout 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.NoUriThis 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
[jc: Narrowed the "except" and tweaked the comment]
Signed-off-by: Jonathan Corbet
27 Jun, 2019
1 commit
-
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
31 May, 2019
1 commit
-
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
Signed-off-by: Jonathan Corbet
30 May, 2019
1 commit
-
There's a new warning about a deprecation function. Add a
logic at cdomain.py to avoid that.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
23 May, 2019
2 commits
-
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 -
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
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