16 Sep, 2016
1 commit
-
Fixed a -> an typo.
Signed-off-by: Robert Foss
Acked-by: Kees Cook
Signed-off-by: Jonathan Corbet
06 Sep, 2016
5 commits
-
Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.Signed-off-by: Jonathan Corbet
-
As far as I can tell, the handling of "..." arguments has never worked
right, so any documentation provided was ignored in favor of "variable
arguments." This makes kernel-doc handle "@...:" as documented. It does
*not* fix spots in kerneldoc comments that don't follow that convention,
but they are no more broken than before.Signed-off-by: Jonathan Corbet
-
This is a trivial fix to correct upper bound addresses to always be
inclusive. Previously, the majority of ranges specified were inclusive with a
small minority specifying an exclusive upper bound. This patch fixes this
inconsistency.Signed-off-by: Lorenzo Stoakes
Signed-off-by: Jonathan Corbet -
The driver that used the 'nodisconnect' parameter was removed in
commit 565bae6a4a8f ("[SCSI] 53c7xx: kill driver"). Related documentation
was cleaned up in commit f37a7238d379 ("[SCSI] 53c7xx: fix removal
fallout"), except for the remaining two mentions that are removed here.Signed-off-by: Finn Thain
Reviewed-by: Geert Uytterhoeven
Signed-off-by: Jonathan Corbet -
- The guide currently says to pad the structure to a multiple of
64-bits. This is not necessary in cases where the structure contains
no 64-bit types. Clarify this concept to avoid unnecessary padding.
- When using __u64 to hold user pointers, blindly trying to do a cast to
a void __user * may generate a warning on 32-bit systems about a cast
from an integer to a pointer of different size. There is a macro to
deal with this which hides an ugly double cast. Add a reference to
this macro.Signed-off-by: Laura Abbott
Acked-by: Arnd Bergmann
Signed-off-by: Jonathan Corbet
01 Sep, 2016
5 commits
-
To build only the PDF of the media folder run::
make SPHINXDIRS=media pdfdocs
Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
This extends the method to build only sub-folders to the targets
"latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
required, where the latex_documents of the sub-folder are
defined. E.g. to build only gpu's PDF add the following to the
Documentation/gpu/conf.py::+latex_documents = [
+ ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
+ "The kernel development community", "manual"),
+]and run:
make SPHINXDIRS=gpu pdfdocs
Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
The setup() function of a Sphinx-extension can return a dictionary. This
is treated by Sphinx as metadata of the extension [1].With metadata "parallel_read_safe = True" a extension is marked as
save for "parallel reading of source". This is needed if you want
build in parallel with N processes. E.g.:make SPHINXOPTS=-j4 htmldocs
will no longer log warnings like:
WARNING: the foobar extension does not declare if it is safe for
parallel reading, assuming it isn't - please ask the extension author
to check and make it explicit.Add metadata to extensions:
* kernel-doc
* flat-table
* kernel-include[1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata
Signed-off-by: Markus Heiser
Tested-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fncSo, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Improve the parser to handle typedefs like:
typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
26 Aug, 2016
1 commit
-
From the old description people still can't get what's the exact
difference between nr_cpus and maxcpus. Especially in kdump kernel
nr_cpus is always suggested if it's implemented in the ARCH. The
reason is nr_cpus is used to limit the max number of possible cpu
in system, the sum of already plugged cpus and hot plug cpus can't
exceed its value. However maxcpus is used to limit how many cpus
are allowed to be brought up during bootup.Signed-off-by: Baoquan He
Signed-off-by: Jonathan Corbet
25 Aug, 2016
1 commit
-
Right now, for a struct, kernel-doc produces the following output:
.. c:type:: struct v4l2_prio_state
stores the priority states
**Definition**
::
struct v4l2_prio_state {
atomic_t prios[4];
};**Members**
``atomic_t prios[4]``
array with elements to store the array prioritiesPutting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
item[atomic_t prios\[4\]] array with elements to store the array prioritiesEverything inside "item" is non-breakable, with may produce
lines bigger than the column width.Also, for function members, like:
int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);
It puts the name of the member at the end, like:
int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read
With is very confusing.
The best is to highlight what really matters: the member name.
is a secondary information.So, change kernel-doc, for it to produce the output on a different way:
**Members**
``prios[4]``
array with elements to store the array priorities
Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.So, both LaTeX/PDF and HTML outputs will look good.
It should be noticed, however, that the way Sphinx LaTeX output handles
things like:Foo
baris different than the HTML output. On HTML, it will produce something
like:**Foo**
barWhile, on LaTeX, it puts both foo and bar at the same line, like:
**Foo** bar
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
23 Aug, 2016
10 commits
-
We need adjustbox to allow adjusting the size of tables that
are bigger than the line width. There are quite a few of them
at the media books.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
When XeLaTeX is in interactive mode, it complains that
py@noticelength already exists. Rename it and declare it
only once to avoid such messages.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Instead of painting the box with gray, let's use a colored
box. IMHO, that makes easier to warn users about some issue
pointed by the Sphinx. It also matches to what we do already
with the HTML output.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
While the current implementation works well when using as a
paragraph, it doesn't work properly if inside a table. As we
have quite a few such cases, fix the logic to take the column
size into account.PS.: I took the logic there from the latest version of Sphinx.sty
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Sphinx supports LaTeX output. Sometimes, it is interesting to
call it directly, instead of also generating a PDF. As it comes
for free, add a target for it.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
This is only one example, demonstrating the benefits of the patch
series. The CEC_DQEVENT ioctl is migrated to the sphinx c-domain and
referred by ":name: CEC_DQEVENT".With this change the indirection using ":ref:`CEC_DQEVENT` is no longer
needed, we can refer the ioctl directly with ":c:func:`CEC_DQEVENT`". As
addition in the index, there is a entry "CEC_DQEVENT (C function)".Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e.
From the origin comit log::
The RST cpp:function handler is very pedantic: it doesn't allow any
macros like __user on itSince the kernel-doc parser does NOT make use of the cpp:domain, there
is no need to change the kernel-doc parser eleminating the address_space
tags.Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
Moved the *duplicate C object description* warnings for function
declarations in the nitpicky mode. In nitpick mode, you can suppress
those warnings (e.g. ioctl) with::nitpicky = True
nitpick_ignore = [
("c:func", "ioctl"),
]See Sphinx documentation for the config values for ``nitpick`` and
``nitpick_ignore`` [1].With this change all the ".. cpp:function:: int ioctl(..)" descriptions
(found in the media book) can be migrated to ".. c:function:: int
ioctl(..)", without getting any warnings. E.g.::.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )
.. c:function:: int ioctl( int fd, int request, struct cec_event *argp )
The main effect, is that we get those *CPP-types* back into Sphinx's C-
namespace and we need no longer to distinguish between c/cpp references,
when we refer a function like the ioctl.[1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky
Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
Add option 'name' to the "c:function:" directive. With option 'name'
the ref-name of a function can be modified. E.g.::.. c:function:: int ioctl( int fd, int request )
:name: VIDIOC_LOG_STATUSThe func-name (e.g. ioctl) remains in the output but the ref-name
changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for
this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
can now referenced by:::c:func:`VIDIOC_LOG_STATUS`
Signed-off-by: Markus Heiser
Signed-off-by: Jonathan Corbet -
Add a sphinx-extension to customize the sphinx c-domain. No functional
changes right yet, just the boilerplate code.Signed-off-by: Markus Heiser
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet
20 Aug, 2016
1 commit
-
Coalesce development-tool documents into a single directory and sphinxify
them.
19 Aug, 2016
16 commits
-
Acked-by: Jan Kiszka
Signed-off-by: Jonathan Corbet -
Cc: Vegard Nossum
Cc: Pekka Enberg
Signed-off-by: Jonathan Corbet -
Acked-by: Catalin Marinas
Signed-off-by: Jonathan Corbet -
Acked-by: Andrey Ryabinin
Signed-off-by: Jonathan Corbet -
No textual changes beyond formatting.
Acked-by: Andrey Ryabinin
Acked-by: Alexander Potapenko
Cc: Dmitry Vyukov
Signed-off-by: Jonathan Corbet -
No textual changes beyond formatting.
Cc: Peter Oberparleiter
Signed-off-by: Jonathan Corbet -
Another document added to the dev-tools collection.
Cc: Dmitry Vyukov
Signed-off-by: Jonathan Corbet -
Fold the sparse document into the development tools set; no changes to the
text itself beyond formatting.Signed-off-by: Jonathan Corbet
-
No textual changes have been made, but the formatting has obviously been
tweaked.Cc: Michal Marek
Cc: Gilles Muller
Acked-by: Nicolas Palix
Acked-by: Julia Lawall
Signed-off-by: Jonathan Corbet -
This directory will be a collecting point for documentation oriented around
development tools. As a step toward ordering Documentation/ it's a small
one, but we have to start somewhere...Signed-off-by: Jonathan Corbet
-
Mauro says:
This patch series fix Sphinx to allow it to build the media
documentation as a PDF file.The first patch is actually a bug fix: one of the previous patch
broke compilation for PDF as a hole, as it added an extra
parenthesis to a function call.The second patch just removes a left over code for rst2pdf.
The other patches change from "pdflatex" to "xelatex" and address
several issues that prevent building the media books.I think this patch series belong to docs-next. Feel free to merge
them there, if you agree. There's one extra patch that touches
Documentation/conf.py, re-adding the media book to the PDF build,
but IMHO this one would be better to be merged via the media tree,
after the fixes inside the media documentation to fix the build. -
This extension will be used by the media books.
The name of the math image extension changed on Sphinx 1.4.x,
according with:
http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmathLet's autodetect, to keep building with versions < 1.4.
Suggested-by: Markus Heiser
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
When building for LaTeX, it stops and enters into interactive
mode on errors. Don't do that, as there are some non-fatal errors
on media books when using Sphinx 1.4.x that we don't know how fix
yet.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Let's escape the LaTeX characters, to avoid troubles when
outputing them.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
As we have big tables, reduce the left/right margins and decrease
the point size to 8pt. Visually, it is still good enough, and
now less tables are too big to be displayed.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
pdflatex doesn't accept using some UTF-8 chars, like
"equal or less than" or "equal or greater than" chars. However,
the media documents use them. So, we need to use XeLaTeX for
conversion, and a font that accepts such characters.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet