docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+
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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Tue, 8 Nov 2016 12:26:07 +0000 (21:26 +0900)]
docs/driver-api: Apply changed source file names
Few files under dma-buf/ changed their names but the changes didn't
applied to a document that referencing them. It is causing few
documentation build warnings. This commit fixes the problems by
applying changed file names on the document.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A typo sneaked in the latest change on the USB documentation. Fixing it
and also a trailing whitespace since it is also in the "USB Host-Side API
Model" chapter.
Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com>
Masahiro Yamada [Wed, 2 Nov 2016 16:57:34 +0000 (01:57 +0900)]
coding-style: fix mismatch of jump label name
Commit 865a1caa4b6b ("CodingStyle: Clarify and complete chapter 7")
renamed the label "out_buffer" to "out_free_buffer", but missed to
change this line.
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com> Reviewed-by: Jean Delvare <jdelvare@suse.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changes since v1:
- Reduce the patch to DocBook cleandocs
References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.com Reported-by: Jim Davis <jim.epost@gmail.com> Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jarkko Sakkinen [Thu, 3 Nov 2016 23:57:51 +0000 (17:57 -0600)]
tpm: transition tpm_vtpm_proxy documentation to the Sphinx
Transitioned the tpm_vtpm_proxy documentation to the Sphinx
infrastructure and removed parts from the documentation that are easier
to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c
to be compatible with this approach and wrote associated documentation
comments.
Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:21 +0000 (05:27 +0900)]
ko_KR/HOWTO: Mark subsection in suggested format
`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format. This commit marks
them in the format.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:20 +0000 (05:27 +0900)]
ko_KR/HOWTO: Add whitespace between URL and text
Because few sentences has no whitespace between URL and text, few
document viewers fail to properly parse the URL from it. This commit
adds whitespace between them to fix the problem.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:14 +0000 (05:27 +0900)]
ko_KR/HOWTO: Convert to ReST notation
This commit applies commit 022e04d6f555 ("Documentation/HOWTO: convert
to ReST notation") to Korean translation and fix a trivial ReST build
failure problem.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Mon, 31 Oct 2016 20:27:10 +0000 (05:27 +0900)]
Documentation/process/howto: Mark subsection in suggested format
`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format. This commit marks
them in the format.
Signed-off-by: SeongJae Park <sj38.park@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Now that oops-tracing.rst has only information about
stack dumps found on OOPS, and bug-hunting.rst has only
information about how to identify the source code line
associated with a stack dump, let's merge them and
improve the information inside it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The document shows a really old procedure for bug hunting that
nobody uses anymore. Remove such section, and update the
remaining documentation to reflect the procedures used
currently.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jani Nikula [Thu, 3 Nov 2016 08:26:54 +0000 (10:26 +0200)]
Documentation/sphinx: set literal block highlight language to none
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 <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com> Cc: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Markus Heiser [Wed, 2 Nov 2016 14:37:11 +0000 (16:37 +0200)]
Documentation/sphinx: fix make SPHINXDIRS="dirs" pdfdocs for more than one dir
Add missing semicolon to fix pdf build with more than one SPHINXDIRS
directory specified. For example make SPHINXDIRS="gpu media" pdfdocs.
Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders") Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Jani Nikula [Wed, 2 Nov 2016 09:13:19 +0000 (11:13 +0200)]
Documentation/sphinx: make it possible to build latexdocs without pdflatex
Building latexdocs doesn't actually require $(PDFLATEX). Move the checks
for it to the pdfdocs target which does require it, and specifically
outside of the target in order to not depend on latexdocs when we can't
build pdfdocs anyway.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Tested-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Jani Nikula [Wed, 2 Nov 2016 08:38:43 +0000 (10:38 +0200)]
Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS
Refer to xelatex and latex options via variables. This allows the user
to override the pdflatex and latex options to use on the make command
line for experimenting. As a side effect, this makes the makefile a bit
tidier.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Jonathan Corbet [Thu, 27 Oct 2016 23:05:10 +0000 (17:05 -0600)]
Merge branch 'doc-tweaks' into docs-next
The creation of the admin and process guides is a great thing, but, without
care, we risk replacing a messy docs directory with a few messy Sphinx
books. In an attempt to head that off and show what I'm thinking, here's a
set of tweaks that, I think, make the existing Sphinx-formatted docs a bit
more accessible.
Oliver Neukum [Thu, 20 Oct 2016 13:15:00 +0000 (15:15 +0200)]
USB: update intro of documentation
It does no good to mention The 2.4 kernel series and neglect
USB 3.x and XHCI. Also with type C and micro/mini USB we better
not talk about the shape of connectors.
Signed-off-by: Oliver Neukum <oneukum@suse.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 26 Oct 2016 22:37:53 +0000 (16:37 -0600)]
docs: Tweak submitting-patches.rst formatting
The main goal here was to get the subsections to show in the TOC as they do
for all the other documents. Also call out the DCO in the section title
since it's important.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 26 Oct 2016 22:14:52 +0000 (16:14 -0600)]
docs: Clean up and organize the admin guide a bit
The admin guide is a good start, but it's time to turn it into something
better than an unordered blob of files. This is a first step in that
direction. The TOC has been split up and annotated, the guides have been
reordered, and minor tweaks have been applied to a few of them.
One consequence of splitting up the TOC is that we don't really want to use
:numbered: anymore, since the count resets every time and there doesn't
seem to be a way to change that. Eventually we probably want to group the
documents into sub-books, at which point we can go back to a single TOC,
but it's probably early to do that.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 26 Oct 2016 21:43:00 +0000 (15:43 -0600)]
docs: Tweak the top-level Sphinx page
This will be the initial landing point for readers, so give them a bit of
introductory material. Also split the TOC into area-specific chunks to
make the whole thing a bit more approachable.
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Markus Heiser [Wed, 26 Oct 2016 06:23:14 +0000 (08:23 +0200)]
doc-rst: make dev-tools folder buildable stand-alone
Add minimal conf.py and moved dev-tools/tools.rst to dev-tools/index.rst
makes the dev-tools folder buildable stand-alone. To build only this
folder run::
make SPHINXDIRS=dev-tools htmldocs
make SPHINXDIRS=dev-tools pdfdocs
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 26 Oct 2016 00:05:23 +0000 (18:05 -0600)]
Merge branch 'mauro-books' into docs-next
Merge Mauro's massive patch series creating the process and admin-guide
books. I think there's a lot of stuff to clean up here, but there's no
point in holding things up for that.
Mauro sez:
This patch series continues the efforts of converting the Linux Kernel
documentation to Sphinx.
It contains text to ReST conversion of several files under Documentation,
and a few ones under the main dir (README, REPORTING-BUGS).
All patches on this series can be found on my development tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books-v2
The Kernel docs html output after this series can be seen at:
https://mchehab.fedorapeople.org/kernel_docs/
README: add a new README file, pointing to the Documentation/
As we moved the real README file to Documentation/admin-guide/README.rst,
let's add a replacement, pointing to it, and giving the main directions
about documentation.
In the future, perhaps it would be worth to move the contents
of Documentation/00-Index into this README.
Those files got moved to Documentation/process, but as they're very
well known files, add pointers to their new locations.
PS.: I opted to not merge this patch with the previous one
in order to make the diff of the previous one more consistent,
as it will show only renames.
Adjust the readme file for it to use the ReST markup:
- add chapter/section markups;
- use ``foo`` for commands;
- use :: for verbatim and script blocks;
- replace unsupported markup _foo_ by **foo**;
- add cross-references to other ReST files;
- use lower case on the section titles, to match other ReST files.
- add a title to the document;
- use :: before verbatim blocks;
- add blank lines where required;
- use protocol for URL references;
- use a verbatim block for the bugs template;
- add cross references to SecurityBugs.
Documentation/VGA-softcursor.txt: convert to ReST markup
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Documentation/unicode.txt: convert it to ReST markup
Probably, unicode is something that we might remove from the
docs, as all modern systems support it. Yet, this chapter
is fun, as it mentions support for the Klington fictional
charset ;)
On the other hand, I bet all other OS user manuals
explicit mention unicode support.
So, convert it to ReST and include it at the user's book.
- Fix document title;
- use a table for the valid commands;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Documentation/sysfs-rules.txt: convert it to ReST markup
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Documentation/ramoops.txt: convert it to ReST format
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
- Add a document title;
- use quote blocks where needed;
- convert parameters to a nested table;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- replace _foo_ by **foo**;
- add it to the user's book.
Documentation/oops-tracing.txt: convert to ReST markup
- Add a document title;
- use .. note:: markup;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- replace _foo_ by **foo**;
- while here, remove whitespaces at the end of paragraph;
- add it to the user's book.
- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
- Fix document title;
- use quote blocks where needed;
- use .. note:: for notes;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
Documentation/module-signing.txt: convert to ReST markup
- Fix identatio for the document title;
- remove its index;
- create a table for hash algorithm to be used;
- use quote blocks where needed;
- use monotonic fonts for parameters;
- adjust whitespaces and blank lines;
- Fix case on section titles;
- add it to the user's book.
- add a title for the document;
- convert some parameters to tables;
- use quote blocks where needed;
- use monotonic fonts for parameters;
- adjust whitespaces and blank lines;
- add it to the user's book.
Documentation/magic-number.txt: convert it to ReST markup
- add a title for the document;
- convert the table;
- use quote block for the changelog;
- use monotonic fonts for file names;
- adjust whitespaces and blank lines;
- add it to the user's book.
- use a quote blocks where needed;
- use ``foo`` for monotonic;
- adjust whitespaces and blank lines;
- fix the second list (that starts with 0, instead of A)
- add it to the user's book.
- use a quote blocks where needed;
- fix the chapter/section/subsection markups;
- use ``foo`` for monotonic;
- use .. note:: for /sbin/init file permissions;
- adjust whitespaces and blank lines;
- add it to the user's book.
Documentation/dynamic-debug-howto.txt: convert it to ReST markup
- use a quote blocks where needed;
- fix the chapter/section/subsection markups;
- use ``foo`` for monotonic;
- use .. note:: for the line-range note;
- cleanup whitespaces;
- add it to the user's book.
Documentation/devices.rst: convert it to ReST markup
- use a quote block for the big device major/minor list;
- use tables for the other device tables;
- fix the chapter/section/subsection markups;
- use ``foo`` for monotonic;
- use .. attention:: for the attention note to developers;
- use cross-references where needed;
- cleanup whitespaces;
- add it to the user's book.
- Add a document title and remove its own index;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust/use spaces to properly format paragraphs;
- add it to the user book.
Documentation/braille-console: convert it to ReST markup
- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: and :kbd: for the menu item and keys;
- point too the right item at the menu;
- add it to the user book.
Documentation/serial-console.txt: convert it to ReST markup
- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: for the menu item;
- add it to the user book.
Documentation/binfmt_misc.txt: convert it to ReST markup
- Fix identation for the document title;
- use monotonic fonts for commands, paths, etc;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- add it to the user book.
projects / linux-beck.git / log