linux/Documentation/sphinx, branch v5.3

docs: load_config.py: ensure subdirs end with "/"

2019-07-19T11:49:27Z

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

docs: load_config.py: avoid needing a conf.py just due to LaTeX docs

2019-07-17T09:57:52Z

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

docs: automarkup.py: ignore exceptions when seeking for xrefs

2019-07-08T20:35:47Z

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 [jc: Narrowed the "except" and tweaked the comment] Signed-off-by: Jonathan Corbet

Docs: An initial automarkup extension for sphinx

2019-06-26T17:14:09Z

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

docs: requirements.txt: recommend Sphinx 1.7.9

2019-05-30T16:42:05Z

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

docs: cdomain.py: get rid of a warning since version 1.8

2019-05-29T21:47:32Z

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

doc: Cope with the deprecation of AutoReporter

2019-05-23T15:23:11Z

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

doc: Cope with Sphinx logging deprecations

2019-05-23T15:22:00Z

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

Documentation/sphinx: allow "functions" with no parameters

2018-06-30T13:52:42Z

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

doc:sphinx: fix parse-header description

2018-06-26T15:07:57Z

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