Dmitry Shachnev [Sun, 18 Dec 2016 10:11:46 +0000 (13:11 +0300)]
docs: sphinx-extensions: make rstFlatTable work with docutils 0.13
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.
Stephan Mueller [Fri, 21 Oct 2016 03:00:02 +0000 (05:00 +0200)]
crypto: doc - optimize compilation
The :functions: definition allows the specification of multiple
function references which prevents parsing the header file multiple
times.
Reported-by: Jani Nikula <jani.nikula@linux.intel.com> Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Stephan Mueller [Fri, 21 Oct 2016 02:58:20 +0000 (04:58 +0200)]
crypto: doc - add KPP documentation
Add the KPP API documentation to the kernel crypto API Sphinx
documentation. This addition includes the documentation of the
ECDH and DH helpers which are needed to create the approrpiate input
data for the crypto_kpp_set_secret function.
Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Stephan Mueller [Fri, 21 Oct 2016 02:54:22 +0000 (04:54 +0200)]
crypto: doc - convert crypto API documentation to Sphinx
With the conversion of the kernel crypto API DocBook to Sphinx, the
monolithic document is broken up into individual documents. The
documentation is unchanged with the exception of a slight reordering to
keep the individual document parts self-contained.
Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Daniel Vetter [Fri, 9 Dec 2016 18:53:05 +0000 (19:53 +0100)]
dma-buf: Extract dma-buf.rst
Just prep work to polish and consolidate all the dma-buf related
documenation.
Unfortunately I didn't discover a way to both integrate this new file
into the overall toc while keeping it at the current place. Work
around that by moving it into the overall driver-api/index.rst.
Cc: linux-doc@vger.kernel.org Cc: Jonathan Corbet <corbet@lwn.net> Cc: Sumit Semwal <sumit.semwal@linaro.org> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Em Mon, 5 Dec 2016 14:23:01 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Mon, 5 Dec 2016 09:41:40 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>
> > So, in order to check it, I wrote a small script that compares the files
> > and directories at Documentation/ with the ones at 00-INDEX.
> >
> > Then, I synchronized the entries, making the script happy.
> >
> > We might think on integrating the script with checkpatch.pl, but, as
> > we should get rid of 00-INDEX, it probably not worth the efforts.
>
> I would agree with that; I don't see the point of keeping those files
> around in the longer term.
>
> I've applied the set. I do have a few quibbles with the final patch that
> I'll send separately, but they're not something to hold this set up for.
Jon,
Did a patch fixing the quibbles.
As it seems you didn't push yet the changeset upstream, feel free to
just fold it with patch 5/5 if you prefer so, or to add as a separate
patch at the end of the series.
Patch enclosed.
Thanks,
Mauro
[PATCH] docs: 00-INDEX: change text related to the building system
Let be clearer on those files related to the build system.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs: 00-INDEX: add missing entries for documentation files/dirs
Several directories and individual files don't have entries at
00-INDEX. Add them, using, as reference, the initial text inside
the documentation file(s).
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs: 00-INDEX: consolidate process/ and admin-guide/ description
Instead of having descriptions for individual files inside
the process/ and admin-guide/ documentation, consolidate them
into one entry per directory, just like other descriptions
inside 00-INDEX.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
scripts: add a script to check if Documentation/00-INDEX is sane
It is easy to forget adding/removing entries at the
Documentation/00-INDEX file. In a matter of fact, even before
ReST conversion, people use to forget adding things here, as
there are lots of missing stuff out there.
Now that we're doing a hard work converting entries to ReST,
and while this hole file is not outdated, it is good to have
some tool that would help to verify that this file is kept
updated.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Document device links as introduced in v4.10 with commits: 4bdb35506b89 ("driver core: Add a wrapper around
__device_release_driver()") 9ed9895370ae ("driver core: Functional dependencies tracking
support") 8c73b4288496 ("PM / sleep: Make async suspend/resume of devices use
device links") 21d5c57b3726 ("PM / runtime: Use device links") baa8809f6097 ("PM / runtime: Optimize the use of device links")
Signed-off-by: Lukas Wunner <lukas@wunner.de>
[ jc: Moved from core-api to driver-api ] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs-rst: replace the selection.png by a SVG image
bitmap images don't scale too well. So, replace it by a SVG
image, written in inkscape. I'm using the 2009's temporary
logo.svg image from 8032b526d1a3 ("linux.conf.au 2009: Tuz"),
with a Tasmanian Devil wearing a tux mask.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The pipeline image was produced from some dot file that has
long missed. Create a pipeline.dot with the graph and convert
it to SVG. As we're planning to add future support for graphviz
graphics, also store the .dot file on the tree, as this will
make easier when we add such Sphinx extension.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Use sans-serif font on all documents, split text lines,
ungroup elements, and do other misc cleanups, in order to make
all of them to look better, and to have smaller columns inside
their lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Using vectorial graphics provide a better visual. As those images
are originally using a vectorial graphics input at the pdf files,
use them, from an old media tree repository, converting them to SVG.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Sat, 19 Nov 2016 00:21:32 +0000 (17:21 -0700)]
doc: Sphinxify the tracepoint docbook
Convert the tracepoint docbook template to RST and add it to the core-api
manual. No changes to the actual text beyond the mechanical formatting
conversion.
Cc: Jason Baron <jbaron@redhat.com> Cc: William Cohen <wcohen@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Sat, 19 Nov 2016 00:17:11 +0000 (17:17 -0700)]
doc: debugobjects: actually pull in the kerneldoc comments
Add the appropriate markup to get the kerneldoc comments out of
lib/debugobjects.c that have never seen the light of day until now.
A logical next step, left for the reader at the moment, is to move the
function descriptions *out* of debug-objects.rst and into the kerneldoc
comments themselves.
Jonathan Corbet [Sat, 19 Nov 2016 00:06:13 +0000 (17:06 -0700)]
doc: Convert the debugobjects DocBook template to sphinx
A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.
Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules. It doesn't work here either :)
Cc: Thomas Gleixner <tglx@linutronix.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Dan Carpenter [Mon, 28 Nov 2016 14:43:15 +0000 (17:43 +0300)]
Documentation/process/howto: Only send regression fixes after -rc1
The original text was not clear if white space or other harmless patches
should be merged in -rc kernels. The discussion at Kernel Summit said
that we should be more strict about sending regression fixes only.
Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
docs-rst: doc-guide: split the kernel-documentation.rst contents
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 <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Daniel Vetter [Thu, 17 Nov 2016 10:19:43 +0000 (11:19 +0100)]
doc: Document the new inline struct member kernel-doc style
We don't just need better doc toolchains, we also need better docs for
our doc toolchain!
v2: Make sure we don't have foo twice (Jani).
Cc: Daniel Vetter <daniel@ffwll.ch> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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>
Takashi Iwai [Thu, 10 Nov 2016 21:19:33 +0000 (22:19 +0100)]
ASoC: doc: ReSTize dapm.txt
A simple conversion from a plain text file.
The section numbers and the item numbers are dropped to align with the
ReST format. Some lists are converted to description lists to be
clearer.
Acked-by: Mark Brown <broonie@kernel.org> Signed-off-by: Takashi Iwai <tiwai@suse.de>
Takashi Iwai [Wed, 9 Nov 2016 14:52:06 +0000 (15:52 +0100)]
ALSA: doc: ReSTize Procfile document
A simple conversion from a text file.
A new subidrectory, Documentation/sound/designs, was created to put
this document. The other API design and implementation docuemnts
will be put to that directory in later commits.
projects / karo-tx-linux.git / log