Johannes Berg [Tue, 11 Oct 2016 12:56:53 +0000 (14:56 +0200)]
docs-rst: sphinxify 802.11 documentation
This is just a very basic conversion, I've split up the original
multi-book template, and also split up the multi-part mac80211
part in the original book; neither of those were handled by the
automatic pandoc conversion.
Fix errors that showed up, resulting in a much nicer rendering,
at least for the interface combinations documentation.
Signed-off-by: Johannes Berg <johannes.berg@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Stephen Bates [Mon, 26 Sep 2016 01:18:37 +0000 (19:18 -0600)]
dax : Fix documentation with respect to struct pages
The documentation for dax is not up to date with respect to the struct
page support available in some of the device drivers that utilize
it.
Signed-off-by: Stephen Bates <sbates@raithlin.com> Acked-by: Ross Zwisler <ross.zwisler@linux.intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Jonathan Corbet [Wed, 21 Sep 2016 21:46:18 +0000 (15:46 -0600)]
docs: Remove space-before-label guidance from CodingStyle
Recent discussion has made it clear that there is no community consensus on
this particular rule. Remove it now, lest it inspire yet another set of
unwanted "cleanup" patches.
This partially reverts 865a1caa4b6b (CodingStyle: Clarify and complete
chapter 7).
Cc: Jean Delvare <jdelvare@suse.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add cross references for the development process documents
that were converted to ReST:
Documentation/SubmitChecklist
Documentation/SubmittingDrivers
Documentation/SubmittingPatches
Documentation/development-process/development-process.rst
Documentation/stable_kernel_rules.txt
Documentation/kernel-docs.txt: get rid of broken docs
There are still some broken docs: the URLs point to somewhere,
however, the texts are not there anymore. I was able to
find the texts on other URLs for some of those, but they're all
too old. So, just get rid of them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/kernel-docs.txt: some improvements on the ReST output
- Use lower case for sections, as this is the standard used on
the other ReST files;
- The latest version of this document is at the Kernel source, and
not at the listed URL. So, move it to the end of the doc.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Books:
------
* Linux Kernel Networking by Rami Rosen
While some parts are quite short and could be
more carefully explained it's still a good recomendation
for understanding linux kernel networking, (IMHO)
* Linux Treiber entwickeln:
It sure is a drawback that this is a german book.
But it's quite recent, well structured and there are also
other non-english (spanish) books/papers in this list.
Papers:
-------
* On Submitting kernel Patches
Contains 2 case studies of bigger patch sets and how (or how not)
they were merged. I found it helpful
* Tracing the Way of Data in a TCP Connection through the Linux Kernel
Since this was written by me this inclusion may be a bit biased :p
Neitherless I think this gives a good introduction on
understanding/exploring linux internals using ftrace and an overview
of Linux TCP internals.
[mchehab@s-opensource.com: rebased to apply before rename]
Signed-off-by: Richard Sailer <richard@weltraumpflege.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Richard Sailer [Tue, 20 Sep 2016 11:36:31 +0000 (08:36 -0300)]
Documentation/kernel-docs.txt: Remove offline or outdated entries
This removes all dead links to online docs which
are dead according to Jon and Mauro in
https://lkml.kernel.org/r/20160916182849.2a7101ea () vento ! lan
Additionally some references to very old articles refering to
linux 2.2 and 2.0 are deleted.
[mchehab@s-opensource.com: rebased to apply before rename]
Signed-off-by: Richard Sailer <richard@weltraumpflege.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Jonathan Corbet [Wed, 21 Sep 2016 00:46:36 +0000 (18:46 -0600)]
docs: Clean up bare :: lines
Mauro's patch set introduced some bare :: lines; these can be represented
by a double colon at the end of the preceding text line. The result looks
a little less weird and is less verbose.
Task 11 (kernel-doc) still mentions usage of make manpages, but
this won't work if the API is documented via Sphinx. So, update
it to use either htmldocs or pdfdocs, with are the documentation
targets that work for all.
While here, add ReST reference to the kernel documentation book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/HOWTO: improve some markups to make it visually better
Do a series of minor improvements at the ReST output format:
- Instead of using the quote blocks (::) for quotes, use
italics. That looks nicer on epub (and html) output, as
no scroll bar will be added. Also, it will adjust line
breaks on the text automatically.
- Add a missing reference to SubmittingPatches.rst and use
**foo** instead of _foo_.
- use bold for "The Perfect Patch" by removing a newline.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/HOWTO: add cross-references to other documents
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.
Documentation/SubmittingPatches: enrich the Sphinx output
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>
Documentation/SubmittingPatches: convert it to ReST markup
- 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>
Documentation/SubmittingDrivers: convert it to ReST markup
- 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>
Documentation/stable_api_nonsense.txt: convert it to ReST markup
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>
Documentation/ManagementStyle: convert it to ReST markup
- 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>
Documentation/CodingStyle: use the proper tag for verbatim font
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>
Documentation/Changes: add minimal requirements for documentation build
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>
- 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>
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>
doc: development-process: convert it to ReST markup
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.
Documentation: kdump: Add description of enable multi-cpus support
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>
Jonathan Corbet [Fri, 16 Sep 2016 16:04:25 +0000 (10:04 -0600)]
Merge branch 'driver-api' into doc/4.9
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!
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.
Jonathan Corbet [Sat, 20 Aug 2016 19:24:56 +0000 (13:24 -0600)]
docs: Pull the HSI documentation together
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>
Jonathan Corbet [Fri, 26 Aug 2016 13:14:08 +0000 (07:14 -0600)]
docs: make kernel-doc handle varargs properly
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.
Lorenzo Stoakes [Tue, 23 Aug 2016 08:00:45 +0000 (09:00 +0100)]
x86: fix memory ranges in mm documentation
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 [Sat, 27 Aug 2016 02:29:59 +0000 (12:29 +1000)]
documentation/scsi: Remove nodisconnect parameter
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>
Laura Abbott [Fri, 2 Sep 2016 22:42:24 +0000 (15:42 -0700)]
doc: ioctl: Add some clarifications to botching-up-ioctls
- 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>
Markus Heiser [Wed, 24 Aug 2016 15:36:14 +0000 (17:36 +0200)]
doc-rst: generic way to build PDF of sub-folders
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>
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.
docs-rst: kernel-doc: fix typedef output in RST format
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.
Baoquan He [Wed, 24 Aug 2016 05:06:45 +0000 (13:06 +0800)]
docs: kernel-parameter: Improve the description of nr_cpus and maxcpus
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>
docs-rst: kernel-doc: better output struct members
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.
docs-rst: Use better colors for note/warning/attention boxes
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>
docs-rst: conf.py: adjust the size of .. note:: tag
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>
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 [Mon, 15 Aug 2016 14:08:28 +0000 (16:08 +0200)]
doc-rst: migrate ioctl CEC_DQEVENT to c-domain
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 [Mon, 15 Aug 2016 14:08:26 +0000 (16:08 +0200)]
doc-rst: moved *duplicate* warnings to nitpicky mode
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::
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.
Markus Heiser [Mon, 15 Aug 2016 14:08:25 +0000 (16:08 +0200)]
doc-rst:c-domain: ref-name of a function declaration
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>
Jonathan Corbet [Sat, 20 Aug 2016 19:17:32 +0000 (13:17 -0600)]
docs: split up the driver book
We don't need to keep it as a single large file anymore; split it up so
that it is easier to manage and the individual sections can be read
directly as plain files.
Jonathan Corbet [Mon, 8 Aug 2016 22:03:14 +0000 (16:03 -0600)]
docs: sphinxify coccinelle.txt and add it to dev-tools
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 [Mon, 8 Aug 2016 22:00:25 +0000 (16:00 -0600)]
docs: create a new dev-tools directory
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...
Jonathan Corbet [Thu, 18 Aug 2016 23:16:14 +0000 (17:16 -0600)]
Merge branch 'xelatex' into doc/4.9
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.
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>
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>
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>
projects / linux-beck.git / log