summaryrefslogtreecommitdiffstats
AgeCommit message (Collapse)AuthorFilesLines
2016-09-20Documentation/HOWTO: add cross-references to other documentsMauro Carvalho Chehab11-9/+27
Add cross references for the documents mentioned at HOWTO and are under the Documentation/ directory, using the ReST notation. It should be noticed that HOWTO also mentions the /README file. We opted to not touch it, for now, as making it build on Sphinx would require it to be moved to a Documentation/foo directory. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/kernel-docs.txt: convert it to ReST markupMauro Carvalho Chehab1-728/+786
This one required lots of manual work, for it to be properly displayed. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-20Documentation/SubmittingPatches: enrich the Sphinx outputMauro Carvalho Chehab1-45/+55
Do a few changes to make the output look better: - use bullets on trivial patches list; - use monotonic font for tools name; - use :manpage:`foo` for man pages; - don't put all references to maintainer*html at the same line. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/SubmittingPatches: convert it to ReST markupMauro Carvalho Chehab1-102/+105
- Change the sections to use ReST markup; - Add cross-references where needed; - convert aspas to verbatim text; - use code block tags; - make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/SubmittingDrivers: convert it to ReST markupMauro Carvalho Chehab1-14/+31
- Change the document title markup to make it on a higher level; - Add blank lines as needed, to improve the output; - use italics for the country-code at kernel.org ftp URL. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/stable_kernel_rules.txt: convert it to ReST markupMauro Carvalho Chehab1-33/+68
- use ReST markups for section headers; - add cross-references to the options; - mark code blocks; - a few minor changes to make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/stable_api_nonsense.txt: convert it to ReST markupMauro Carvalho Chehab1-11/+24
Add markups for it to be properly parsed by Sphinx. As people browsing this document may not notice that the source file title is "stable_api_nonsense", I opted to use bold to the rationale for this document. I also found it better to add a note when it says that the nonsense applies only to the kABI/kAPI, and not to uAPI. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/SecurityBugs: convert it to ReST markupMauro Carvalho Chehab1-0/+6
Add a name for the document and convert the sections to ReST markups. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/ManagementStyle: convert it to ReST markupMauro Carvalho Chehab1-72/+82
- Convert document name to ReST; - Convert footnotes; - Convert sections to ReST format; - Don't use _foo_, as Sphinx doesn't support underline. Instead, use bold; - While here, remove whitespaces at the end of lines. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/CodingStyle: use the .. note:: markup where neededMauro Carvalho Chehab1-5/+9
There are two places there where there are notes that should be highlighted. So, use the ReST note markup for such texts. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/CodingStyle: replace underline markupsMauro Carvalho Chehab1-16/+16
Sphinx doesn't accept underline markups by purpose. While there are ways to support underline via CSS, this won't be portable with non-html outputs. As we want CodingStyle to do emphasis, replace _foo_ by **foo**, using bold emphasis. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/CodingStyle: use the proper tag for verbatim fontMauro Carvalho Chehab1-49/+49
On Sphinx/ReST notation, ``foo`` means that foo will be will be marked as inline literal, effectively making it to be presented as a monospaced font. As we want this document to be parsed by Sphinx, instead of using "foo", use ``foo`` for the names that are literal, because it is an usual typographic convention to use monospaced fonts for functions and language commands on documents, and we're following such convention on the other ReST books. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/CodingStyle: Convert to ReST markupMauro Carvalho Chehab1-79/+182
- Fix all chapter identation; - add c blocks where needed; Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/Changes: add minimal requirements for documentation buildMauro Carvalho Chehab1-1/+35
As discussed at linux-doc ML, the best is to keep all documents backward compatible with Sphinx version 1.2, as it is the latest version found on some distros like Debian. All books currently support it. Please notice that, while it mentions the eventual need of XeLaTex and texlive to build pdf files, this is not a minimal requirement, as one could just be interested on building html documents. Also, identifying the minimal requirements for texlive packages is not trivial, as each distribution seems to use different criteria on grouping LaTex functionalities. While here, update the current kernel version to 4.x. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/Changes: convert it to ReST markupMauro Carvalho Chehab1-90/+134
- Fix chapter identation inconsistencies; - Convert table to ReST format; - use the right tag for bullets; - Fix bold emphasis; - mark blocks with :: tags; - use verbatim font for files; - make Sphinx happy Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/applying-patches.txt: Update the information thereMauro Carvalho Chehab1-145/+110
This document is old: it is from Kernel v2.6.12 days. Update it to the current status, and add a reference for the linux-next tree. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/applying-patches.txt: convert it to ReST markupMauro Carvalho Chehab1-123/+190
- use the correct markup to identify each section; - Add some blank lines for Sphinx to properly interpret the markups; - Remove a blank space on some paragraphs; - Fix the verbatim and bold markups; - Cleanup the remaining errors to make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation/HOWTO: convert to ReST notationMauro Carvalho Chehab1-4/+49
This document is almost compliant with ReST notation, but some small adjustments are needed to make it parse properly by Sphinx (mostly, add blank lines where needed). Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20docs-rst: create a book for the development processMauro Carvalho Chehab4-0/+22
Now that the files at Documentation/development-process/ were converted to ReST, make create a book at Sphinx. As we'll have other books related to the development process, we'll add it as a sub-book. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20doc: development-process: rename files to rstMauro Carvalho Chehab8-0/+0
Now that the documents were converted, rename them to .rst, as this is needed by the Sphinx build logic. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20doc: development-process: convert it to ReST markupMauro Carvalho Chehab9-86/+179
This document is on good shape for ReST: all it was needed was to fix the section markups, add a toctree, convert the tables and add a few code/quote blocks. While not strictly required, I opted to use lowercase for the titles, just like the other books that were converted to Sphinx. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-20doc-rst: add CSS styles for :kbd: and :menuselection:Mauro Carvalho Chehab1-1/+14
As we're about to use those two markups, add them to the theme style overrride. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation: kdump: Add description of enable multi-cpus supportZhou Wenjian1-0/+7
Multi-cpu support is useful to improve the performance of kdump in some cases. So add the description of enable multi-cpu support in dump-capture kernel. Signed-off-by: Zhou Wenjian <zhouwj-fnst@cn.fujitsu.com> Acked-by: Baoquan He <bhe@redhat.com> Acked-by: Xunlei Pang <xpang@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation: kdump: Remind user of nr_cpusZhou Wenjian1-0/+2
nr_cpus can help to save memory. So we should remind user of it. Signed-off-by: Zhou Wenjian <zhouwj-fnst@cn.fujitsu.com> Acked-by: Baoquan He <bhe@redhat.com> Acked-by: Xunlei Pang <xpang@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20Documentation: DMA-API-HOWTO: Fix a typoAndrey Smirnov1-1/+1
Fix a type in example variable name. Signed-off-by: Andrey Smirnov <andrew.smirnov@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16Merge branch 'driver-api' into doc/4.9Jonathan Corbet16-598/+734
This short series convers device-drivers.tmpl into the RST format, splits it up, and sets up the result under Documentation/driver-api/. For added fun, I've taken one top-level file (hsi.txt) and folded it into the document as a way of showing the direction I'm thinking I would like things to go. There is plenty more of this sort of work that could be done, to say the least - this is just a beginning! The formatted results can be seen at: http://static.lwn.net/kerneldoc/driver-api/index.html As part of the long-term task to turn Documentation/ into less of a horror movie, I'd like to collect documentation of the driver-specific API here. Arguably gpu/ and the media API stuff should eventually move here, though we can discuss the color of that particular shed some other day. Meanwhile, I'd appreciate comments on the general idea.
2016-09-16docs/driver-model: fix typoLaurent Navet1-1/+1
No need to be be, just be should be sufficient. Signed-off-by: Laurent Navet <laurent.navet@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16DMA-API-HOWTO: <asm/generic/scatterlist.h> is no moreChristoph Hellwig1-4/+2
So don't mention it. Signed-off-by: Christoph Hellwig <hch@lst.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16doc-rst:c-domain: function-like macros argumentsMarkus Heiser1-1/+54
Handle signatures of function-like macros well. Don't try to deduce arguments types of function-like macros. Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16doc-rst:c-domain: fix sphinx version incompatibilityMarkus Heiser1-2/+12
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>
2016-09-16Documentation/filesystems: Fixed typoRobert Foss1-1/+1
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>
2016-09-06docs: Don't format internal MPT docsJonathan Corbet1-18/+0
This is the driver API document, so the internal stuff is just noise here. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06docs: split up serial-interfaces.rstJonathan Corbet5-190/+190
It never made sense to keep these documents together; move each into its own file. Drop the section numbering on hsi.txt on its way to its own file. Suggested-by: Sebastian Reichel <sre@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06docs: Pull the HSI documentation togetherJonathan Corbet3-80/+79
The HSI subsystem documentation was split across hsi.txt and the device-drivers docbook. Now that the latter has been converted to Sphinx, pull in the HSI document so that it's all in one place. Acked-by: Sebastian Reichel <sre@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06docs: Special-case function-pointer parameters in kernel-docJonathan Corbet1-0/+2
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>
2016-09-06docs: make kernel-doc handle varargs properlyJonathan Corbet1-1/+2
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>
2016-09-06x86: fix memory ranges in mm documentationLorenzo Stoakes1-3/+3
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>
2016-09-06documentation/scsi: Remove nodisconnect parameterFinn Thain2-4/+0
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 <fthain@telegraphics.com.au> Reviewed-by: Geert Uytterhoeven <geert@linux-m68k.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06doc: ioctl: Add some clarifications to botching-up-ioctlsLaura Abbott1-5/+8
- 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>
2016-09-01doc-rst: define PDF's of the media folderMarkus Heiser1-0/+5
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>
2016-09-01doc-rst: generic way to build PDF of sub-foldersMarkus Heiser1-2/+2
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>
2016-09-01docs: sphinx-extensions: add metadata parallel-safeMarkus Heiser3-0/+21
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>
2016-09-01docs-rst: kernel-doc: fix typedef output in RST formatMauro Carvalho Chehab1-10/+24
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>
2016-09-01docs-rst: improve typedef parserMauro Carvalho Chehab1-1/+3
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>
2016-08-25docs: kernel-parameter: Improve the description of nr_cpus and maxcpusBaoquan He1-7/+13
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>
2016-08-24docs-rst: kernel-doc: better output struct membersMauro Carvalho Chehab1-1/+1
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>
2016-08-22docs-rst: add package adjustboxMauro Carvalho Chehab1-0/+3
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>
2016-08-22docs-rst: Fix an warning when in interactive modeMauro Carvalho Chehab1-5/+5
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>
2016-08-22docs-rst: Use better colors for note/warning/attention boxesMauro Carvalho Chehab1-10/+24
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>
2016-08-22docs-rst: conf.py: adjust the size of .. note:: tagMauro Carvalho Chehab1-1/+7
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>