- Sep 16, 2016
-
-
Markus Heiser authored
The self.indexnode's tuple has changed in sphinx version 1.4, from a former 4 element tuple to a 5 element tuple. https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c Signed-off-by:
Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Robert Foss authored
Fixed a -> an typo. Signed-off-by:
Robert Foss <robert.foss@collabora.com> Acked-by:
Kees Cook <keescook@chromium.org> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Sep 06, 2016
-
-
Jonathan Corbet authored
Add yet another regex to kernel-doc to trap @param() references separately and not produce corrupt RST markup. Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
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 <corbet@lwn.net>
-
Lorenzo Stoakes authored
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 <lstoakes@gmail.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Finn Thain authored
The driver that used the 'nodisconnect' parameter was removed in commit 565bae6a ("[SCSI] 53c7xx: kill driver"). Related documentation was cleaned up in commit f37a7238 ("[SCSI] 53c7xx: fix removal fallout"), except for the remaining two mentions that are removed here. Signed-off-by:
Finn Thain <fthain@telegraphics.com.au> Reviewed-by:
Geert Uytterhoeven <geert@linux-m68k.org> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Laura Abbott authored
- 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 <labbott@redhat.com> Acked-by:
Arnd Bergmann <arnd@arndb.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Sep 01, 2016
-
-
Markus Heiser authored
To build only the PDF of the media folder run:: make SPHINXDIRS=media pdfdocs Signed-off-by:
Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
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 <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
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 <markus.heiser@darmarIT.de> Tested-by:
Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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_fnc So, 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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Aug 26, 2016
-
-
Baoquan He authored
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 <bhe@redhat.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Aug 25, 2016
-
-
Mauro Carvalho Chehab authored
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 priorities Putting 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 priorities Everything 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 bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar Signed-off-by:
Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Aug 23, 2016
-
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
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 <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
This reverts commit a88b1672 . From the origin comit log:: The RST cpp:function handler is very pedantic: it doesn't allow any macros like __user on it Since 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 <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
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 <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
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_STATUS The 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 <markus.heiser@darmarIT.de> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Markus Heiser authored
Add a sphinx-extension to customize the sphinx c-domain. No functional changes right yet, just the boilerplate code. Signed-off-by:
Markus Heiser <markus.heiser@darmarIT.de> [ jc: coding-style tweak ] Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
- Aug 20, 2016
-
-
Jonathan Corbet authored
Coalesce development-tool documents into a single directory and sphinxify them.
-
- Aug 19, 2016
-
-
Jonathan Corbet authored
Acked-by:
Jan Kiszka <jan.kiszka@siemens.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
Cc: Vegard Nossum <vegardno@ifi.uio.no> Cc: Pekka Enberg <penberg@kernel.org> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
Acked-by:
Catalin Marinas <catalin.marinas@arm.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
Acked-by:
Andrey Ryabinin <aryabinin@virtuozzo.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
No textual changes beyond formatting. Acked-by:
Andrey Ryabinin <aryabinin@virtuozzo.com> Acked-by:
Alexander Potapenko <glider@google.com> Cc: Dmitry Vyukov <dvyukov@google.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
No textual changes beyond formatting. Cc: Peter Oberparleiter <oberpar@linux.vnet.ibm.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
Another document added to the dev-tools collection. Cc: Dmitry Vyukov <dvyukov@google.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
Fold the sparse document into the development tools set; no changes to the text itself beyond formatting. Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
No textual changes have been made, but the formatting has obviously been tweaked. Cc: Michal Marek <mmarek@suse.com> Cc: Gilles Muller <Gilles.Muller@lip6.fr> Acked-by:
Nicolas Palix <nicolas.palix@imag.fr> Acked-by:
Julia Lawall <julia.lawall@lip6.fr> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Jonathan Corbet authored
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 <corbet@lwn.net>
-
Jonathan Corbet authored
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.
-
Mauro Carvalho Chehab authored
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.imgmath Let's autodetect, to keep building with versions < 1.4. Suggested-by:
Markus Heiser <markus.heiser@darmarit.de> Signed-off-by:
Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
Let's escape the LaTeX characters, to avoid troubles when outputing them. Signed-off-by:
Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Mauro Carvalho Chehab authored
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 <mchehab@s-opensource.com> Signed-off-by:
Jonathan Corbet <corbet@lwn.net>
-