linux.git/Documentation/conf.py, branch v4.11

Documentation/sphinx: fix primary_domain configuration

2017-03-03T23:12:30+00:00

With Sphinx 1.5.3 I get the warning:

	WARNING: primary_domain 'C' not found, ignored.

It seems that domain names in Sphinx are case-sensitive and for the C
domain the name must be lower case.

Signed-off-by: John Keeping 
Signed-off-by: Jonathan Corbet

docs: Remove the copyright year from conf.py

2017-02-06T18:52:19+00:00

It had gone stale, of course, as it would every year, a single date doesn't
really cover things, and the date isn't really needed anyway.

docs-rst: doc-guide: split the kernel-documentation.rst contents

2016-11-19T17:22:04+00:00

Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

docs: Add more manuals to the PDF build

2016-11-16T23:07:02+00:00

There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

Signed-off-by: Jonathan Corbet

docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+

2016-11-16T22:20:12+00:00

PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.

The solution is to redefine the \DURole macro.

However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.

Tested by building the documentation on interactive mode:
	make PDFLATEX=xelatex -C Documentation/output/./latex

Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

Documentation/sphinx: set literal block highlight language to none

2016-11-03T10:38:47+00:00

Set the default highlight language to "none", i.e. do not try to guess
the language and do automatic syntax highlighting on literal blocks.

Eyeballing around the generated documentation, we don't seem to actually
have a lot of literal blocks that would benefit from syntax
highlighting. The C code blocks we do have are typically very short, and
most of the literal blocks are things that shouldn't be highlighted (or,
do not have a pygments lexer). This seems to be true for literal blocks
both in the rst source files and in source code comments.

Not highlighting code is never wrong, but guessing the language wrong
almost invariably leads to silly or confusing highlighting.

At the time of writing, admin-guide/oops-tracing.rst and
admin-guide/ramoops.rst contain good examples of 1) a small C code
snippet not highlighted, 2) a hex dump highligted as who knows what, 3)
device tree block highlighted as C or maybe Python, 4) a terminal
interaction highlighted as code in some language, and finally, 5) some C
code snippets correctly identified as C. I think we're better off
disabling language guessing, and going by explicitly identified
languages for longer code blocks.

It is still possible to enable highlighting on an rst source file basis
using the highlight directive:

.. higlight:: language

and on a literal block basis using the code-block directive:

.. code-block:: language

See http://www.sphinx-doc.org/en/latest/markup/code.html for details.

Cc: Jonathan Corbet 
Cc: Mauro Carvalho Chehab 
Cc: Markus Heiser 
Signed-off-by: Jani Nikula

Documentation/sphinx: include admin-guide in the latex/pdf build

2016-11-03T10:38:25+00:00

Fix the warning:

WARNING: "latex_documents" config value references unknown document
user/index

Reviewed-by: Mauro Carvalho Chehab 
Signed-off-by: Jani Nikula

docs-rst: create an user's manual book

2016-10-24T10:12:35+00:00

Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.

As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.

Signed-off-by: Mauro Carvalho Chehab

docs: rename development-process/ to process/

2016-10-24T10:12:35+00:00

As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.

Signed-off-by: Mauro Carvalho Chehab

Documentation/sphinx: rename kernel-doc.py to kerneldoc.py

2016-10-19T22:02:00+00:00

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