21 Jul, 2016
1 commit
-
Now that the new Sphinx world order is taking over, the information in
kernel-doc-nano-HOWTO.txt is outmoded. I hate to remove it altogether,
since it's one of those files that people expect to find. But we can add a
warning and fix all the other pointers to it.Reminded-by: Daniel Vetter
Signed-off-by: Jonathan Corbet
20 Jul, 2016
1 commit
-
Unfortunately warnings generated after parsing in sphinx can end up
with entirely bogus files and line numbers as sources. Strangely for
outright errors this is not a problem. Trying to convert warnings to
errors also doesn't fix it.The only way to get useful output out of sphinx to be able to root
cause the error seems to be enabling keep_warnings, which inserts
a System Message into the actual output. Not pretty at all, but I
don't really want to fix up core rst/sphinx code, and this gets the job
done meanwhile.Cc: Markus Heiser
Cc: Jonathan Corbet
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter
Signed-off-by: Jonathan Corbet
18 Jul, 2016
2 commits
-
Commit 795ae7a0de6b ("mm: scale kswapd watermarks in proportion to
memory") properly added the description of the new knob to
Documentation/sysctl/vm.txt, but forgot to add it to the list of files
in /proc/sys/vm. Let's fix that.Signed-off-by: Jerome Marchand
Acked-by: Johannes Weiner
Signed-off-by: Jonathan Corbet -
Sphinx wants to interpret all literal blocks as being in the chosen
language and complains when an attempt to parse a block fails.
kernel-documentation.rst has a few blocks that are not in C; make that
explicit to shut down the associated warnings.Signed-off-by: Jonathan Corbet
10 Jul, 2016
1 commit
-
Sometimes, we want to do a partial build, instead of building
everything. However, right now, if one wants to build just
Sphinx books, it will build also the DocBooks.Add an option to allow to ignore all DocBooks when building
documentation.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
06 Jul, 2016
1 commit
-
This patch fixes a spelling typo in workqueue.txt
Signed-off-by: Masanari Iida
Acked-by: Tejun Heo
Signed-off-by: Jonathan Corbet
02 Jul, 2016
3 commits
-
This patch fix some spelling typo found in ocfs2-online-filecheck.txt
Signed-off-by: Masanari Iida
Signed-off-by: Jonathan Corbet -
If the user requested specific DocBooks to be built using 'make
DOCBOOKS=foo.xml htmldocs', assume no Sphinx build is desired. This
check is transitional, and can be removed once we drop the DocBook
build.Cc: Markus Heiser
Cc: Mauro Carvalho Chehab
Fixes: 22cba31bae9d ("Documentation/sphinx: add basic working Sphinx configuration and build")
Signed-off-by: Jani Nikula
Signed-off-by: Jonathan Corbet -
This was broken when updating the documentation targets for the Sphinx
build, and moving from %docs target pattern to explicitly listed
targets.Cc: Markus Heiser
Cc: Mauro Carvalho Chehab
Fixes: 22cba31bae9d ("Documentation/sphinx: add basic working Sphinx configuration and build")
Signed-off-by: Jani Nikula
Signed-off-by: Jonathan Corbet
01 Jul, 2016
3 commits
-
Signed-off-by: Jonathan Corbet
-
This patch fix a spelling typo in intel_powerclamp.txt
Signed-off-by: Masanari Iida
Signed-off-by: Jonathan Corbet -
Implements the reST flat-table directive.
The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:* column-span: with the role ``cspan`` a cell can be extended through
additional columns* row-span: with the role ``rspan`` a cell can be extended through
additional rows* auto span rightmost cell of a table row over the missing cells on the right
side of that table-row. With Option ``:fill-cells:`` this behavior can
changed from *auto span* to *auto fill*, which automaticly inserts (empty)list tables
The *list tables* formats are double stage lists. Compared to the
ASCII-art they migth be less comfortable for readers of the
text-files. Their advantage is, that they are easy to create/modify
and that the diff of a modification is much more meaningfull, because
it is limited to the modified content.The initial implementation was taken from the sphkerneldoc project [1]
[1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py
Signed-off-by: Markus Heiser
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet
24 Jun, 2016
1 commit
-
Describe Sphinx, reStructuredText, the kernel-doc extension, the
kernel-doc structured documentation comments, etc.The kernel-doc parts are based on kernel-doc-nano-HOWTO.txt, by Tim
.Signed-off-by: Jani Nikula
Signed-off-by: Jonathan Corbet
23 Jun, 2016
6 commits
-
Signed-off-by: Michal Nazarewicz
Signed-off-by: Jonathan Corbet -
In the current Documentation/md.txt, the lower limit value of
stripe_cache_size is 16 and the default value is 128, but when
I update kernel to the latest mainline version and RAID5 array
is created by mdadm, then execute the following commands, it
shows an error and a difference respectively.1) set stripe_cache_size to 16
[root@localhost ~]# echo 16 > /sys/block/md0/md/stripe_cache_size
bash: echo: write error: Invalid argument
2) read the default value of stripe_cache_size
[root@localhost ~]# cat /sys/block/md0/md/stripe_cache_size
256I read drivers/md/raid5.c and find the following related code:
1) in function 'raid5_set_cache_size':
if (size 32768)
return -EINVAL;
2) #define NR_STRIPES 256So the lower limit value of stripe_cache_size should be 17 and
the default value should be 256.Signed-off-by: Tiezhu Yang
Signed-off-by: Jonathan Corbet -
Signed-off-by: Eric Wheeler
Cc: Marc MERLIN
Signed-off-by: Jonathan Corbet -
Bcache documentation updates:
- Added new HOWTO/COOKBOOK section
- fixed a few typos
- /sys/block/bcache0/cache_mode is /sys/block/bcache0/bcache/cache_modeSigned-off-by: Marc MERLIN
Signed-off-by: Jonathan Corbet -
While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.Signed-off-by: Jani Nikula
-
The modindex is for python modules.
Signed-off-by: Jani Nikula
10 Jun, 2016
5 commits
-
Let the user specify file patterns where to look for the EXPORT_SYMBOLs
in addition to the file with kernel-doc comments. This is directly based
on the -export-file FILE option added to kernel-doc in "kernel-doc: add
support for specifying extra files for EXPORT_SYMBOLs", but we extend
that with globbing patterns in the Sphinx extension.The file patterns are added as options to the :export: and :internal:
arguments of the kernel-doc directive. For example, to extract the
documentation of exported functions from include/net/mac80211.h:.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.cWithout the file pattern, no exported functions would be found, as the
EXPORT_SYMBOLs are placed in the various source files under
net/mac80211.The matched files are also added as dependencies on the document in
Sphinx, as they may affect the output. This is one of the reasons to do
the globbing in the Sphinx extension instead of in scripts/kernel-doc.The file pattern remains optional, and is not needed if the kernel-doc
comments and EXPORT_SYMBOLs are placed in the source file passed in as
the main argument to the kernel-doc directive. This is the most common
case across the kernel source tree.Signed-off-by: Jani Nikula
-
Using the default str.split doesn't return empty strings like the
current version does.Signed-off-by: Jani Nikula
-
Leftover cruft. No functional changes.
Signed-off-by: Jani Nikula
-
The meaning of "leak" can be both "untracked resource allocation" and
"memory content disclosure". This document's use was entirely of the
latter meaning, so avoid the confusion by using the Common Weakness
Enumeration name for this: Information Exposure (CWE-200). Additionally
adds a section on structure randomization.Signed-off-by: Kees Cook
Signed-off-by: Jonathan Corbet -
Jani Nikula says:
Jon, this is v2 of [1] and [2], with a considerable amount of polish and
fixes added. We started dogfooding this within drm-intel, and Daniel has
reviewed the lot and contributed a number of fixes, most notably
accurate file and line number references from Sphinx build
errors/warnings to the kernel-doc comments in source code.We believe this is now in good shape for merging for v4.8. It's all in
my sphinx-for-docs-next branch that you've already looked at; pull
details below.When this lands in docs-next and we can backmerge to drm, we'll plunge
ahead and convert gpu.tmpl to rst, and have that ready for v4.8. We
think it's best to contribute that via the drm tree, as it'll involve
splitting up the documentation and likely numerous updates to kernel-doc
comments.I plan to update Documentation/kernel-doc-nano-HOWTO.txt for Sphinx and
rst, obviously converting it to rst while at it.
04 Jun, 2016
6 commits
-
Design is pretty simple: kernel-doc inserts breadcrumbs with line
numbers, and sphinx picks them up. At first I went with a sphinx
comment, but inserting those at random places seriously upsets the
parser, and must be filtered. Hence why this version now uses "#define
LINEO " since one of these ever escape into output it's pretty clear
there is a bug.It seems to work well, and at least the 2-3 errors where sphinx
complained about something that was not correct in kernel-doc text the
line numbers matched up perfectly.v2: Instead of noodling around in the parser state machine, create
a ViewList and parse it ourselves. This seems to be the recommended
way, per Jani's suggestion.v3:
- Split out ViewList pach. Splitting the kernel-doc changes from the
sphinx ones isn't possible, since emitting the LINENO lines wreaks
havoc with the rst formatting. We must filter them.- Improve the regex per Jani's suggestions, and compile it just once
for speed.- Now that LINENO lines are eaten, also add them to function parameter
descriptions. Much less content and offset than for in-line struct
member descriptions, but still nice to know which exact continuation
line upsets sphinx.- Simplify/clarify the line +/-1 business a bit.
v4: Split out the scripts/kernel-doc changes and make line-numbers
opt-in, as suggested by Jani.Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
Signed-off-by: Niklas Söderlund
Signed-off-by: Jonathan Corbet -
Chinese version CodingStyle is a little outdate, it should be updated.
This patch sync with the latest CodingStyle of all changes,
new chapters (chapter 19 and chapter 20) have been translated.Signed-off-by: Andy Deng
Signed-off-by: Jonathan Corbet -
It took me browsing through the source code to determine that I was,
indeed, using the wrong delimiter in my command lines. So I might as
well document it for the next person.Signed-off-by: Brian Norris
Acked-by: Steven Rostedt
Signed-off-by: Jonathan Corbet -
The compilation emits a warning in function ‘snprintf’,
inlined from ‘set_cmdline’ at
../Documentation/mic/mpssd/mpssd.c:1541:9:
/usr/include/x86_64-linux-gnu/bits/stdio2.h:64:10:
warning: call to __builtin___snprintf_chk will always overflow
destination bufferThis was introduced in commit f4a66c204482 ("misc: mic: Update MIC host
daemon with COSM changes") and is fixed by reverting the changes to the
size argument of these snprintf statements.Cc: Ashutosh Dixit
Signed-off-by: Mike Danese
Signed-off-by: Jonathan Corbet -
There are two sentences in the Sync File documentation where the
english is a little off. This patch is an attempt to fix these.Signed-off-by: Javier Martinez Canillas
Reviewed-by: Gustavo Padovan
Signed-off-by: Jonathan Corbet
03 Jun, 2016
1 commit
-
Instead of just forcefully inserting our kernel-doc input and letting
the state machine stumble over it the recommended way is to create
ViewList, parse that and then return the list of parsed nodes.Suggested by Jani.
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula
01 Jun, 2016
2 commits
-
With this error output becomes almost readable. The line numbers are
still totally bonghits, but that's a lot harder to pull out of
kerneldoc. We'd essentially have to insert some special markers in the
kernel-doc output, split the output along these markers and then
insert each block separately usingstate_machine.insert_input(block, source, first_line)
Cc: Jani Nikula
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet
Signed-off-by: Daniel Vetter
Signed-off-by: Jani Nikula -
Reconcile differences between python2 and python3 on dealing with
stdout, stderr from Popen. This fixes "name 'unicode' is not defined"
errors on python3. We'll need to try to keep the extension working on
both python-sphinx and python3-sphinx so we don't need two copies.Reported-and-tested-by: Marius Vlad
Signed-off-by: Jani Nikula
30 May, 2016
7 commits
-
Add "struct" in the label of the reference.
Signed-off-by: Jani Nikula
-
Function references should include the parens (), struct references
should not include "struct".Signed-off-by: Jani Nikula
-
This script uses pandoc to convert existing DocBook template files to RST
templates. A couple of sed scripts are need to massage things both before
and after the conversion, but the result is then usable with no hand
editing.[Jani: Change usage to tmplcvt . Fix escaping for docproc
directives. Add support the new kernel-doc extension.]Signed-off-by: Jonathan Corbet
Signed-off-by: Jani Nikula -
Read the version and release from the top level Makefile (for use when
Sphinx is invoked directly, by e.g. Read the Docs), but override them
via Sphinx command line arguments in a normal documentation build.Signed-off-by: Jani Nikula
-
Tell Sphinx where to find the extension, and pass on the kernel src tree
and kernel-doc paths to the extension.With this, any .rst files under Documentation may contain the kernel-doc
rst directive to include kernel-doc documentation from any source file.While building, it may be handy to pass kernel-doc extension
configuration on the command line. For example, 'make SPHINXOPTS="-D
kerneldoc_verbosity=0" htmldocs' silences all stderr output from
kernel-doc when the kernel-doc exit code is 0. (The stderr will be
logged unconditionally when the exit code is non-zero.)Signed-off-by: Jani Nikula
-
Add an extension to handle kernel-doc directives, to call kernel-doc
according to the arguments and parameters given to the reStructuredText
directive.The syntax for the kernel-doc directive is:
.. kernel-doc:: FILENAME
:export:
:internal:
:functions: FUNCTION [FUNCTION ...]
:doc: SECTION TITLEOf the directive options export, internal, functions, and doc, currently
only one option may be given at a time.The FILENAME is relative from the kernel source tree root.
The extension notifies Sphinx about the document dependency on FILENAME,
causing the document to be rebuilt when the file has been changed.Signed-off-by: Jani Nikula
-
The Sphinx output directory is generated.
Signed-off-by: Jani Nikula