Jani Nikula [Wed, 16 Nov 2016 15:26:16 +0000 (17:26 +0200)]
kernel-doc: add support for one line inline struct member doc comments
kernel-doc supports documenting struct members "inline" since a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:
/**
* struct foo - struct documentation
*/
struct foo {
/**
* @bar: member documentation
*/
int bar;
};
Add support for one line inline comments:
/**
* struct foo - struct documentation
*/
struct foo {
/** @bar: member documentation */
int bar;
};
Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.
Cc: Daniel Vetter <daniel@ffwll.ch> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Brian Norris [Tue, 15 Nov 2016 22:42:14 +0000 (14:42 -0800)]
docs/completion.txt: drop dangling reference to completions-design.txt
Per the original author, the proposed document was never deemed
necessary, and the important bits got merged into completion.txt. Let's
just stop confusing readers by pointing at a nonexistent doc.
Signed-off-by: Brian Norris <briannorris@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mark Rutland [Wed, 16 Nov 2016 11:12:49 +0000 (11:12 +0000)]
Documentation: circular-buffers: use READ_ONCE()
While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the circular buffer documentation uses the latter
exclusively.
To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use
READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
circular buffer documentation.
Signed-off-by: Mark Rutland <mark.rutland@arm.com> Acked-by: David Howells <dhowells@redhat.com> Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mark Rutland [Wed, 16 Nov 2016 11:13:59 +0000 (11:13 +0000)]
Documentation: atomic_ops: use {READ,WRITE}_ONCE()
While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.
To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.
Signed-off-by: Mark Rutland <mark.rutland@arm.com> Cc: Boqun Feng <boqun.feng@gmail.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Will Deacon <will.deacon@arm.com> Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 16 Nov 2016 22:39:56 +0000 (15:39 -0700)]
Merge branch 'mauro-pdf' into docs-next
Mauro says:
This series address a series of errors during PDF generation from
media documentation.
The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.
The next two patches fix PDF output issues with subdev-formats.rst.
The next 3 patches fix image includes and their output for PDF.
It is aligned with Linus request of not having binary-generated images
from their SVG source codes.
I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.
It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.
[jc: added a commit fixing up a "make cleandocs" warning]
The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.
Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.
For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.
So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.
NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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.
projects / linux-beck.git / log