The original link is empty, replace it.
Signed-off-by: NCao jin <caoj.fnst@cn.fujitsu.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Commit 9d85025b ("docs-rst: create an user's manual book") moved the
sysrq.txt leaving old paths in the kernel docs.
Signed-off-by: NKrzysztof Kozlowski <krzk@kernel.org>
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The format of the structure references in device_link.rst is
incorrect, because it doesn't cause proper references to the
struct data types to be generated (for struct dev_pm_domain in
particular).

Fix that by using the :c:type:`struct name <name>` convention
for encoding references to struct data types.

Fixes: aad80040 (Documentation/core-api/device_link: Add initial documentation)
Signed-off-by: NRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There is a better way to represent structure references than it was
done in device.rst by commit 730c4c05 (PM / sleep / docs: Convert
PM notifiers document to reST), which is to use "struct name" as a
link caption (e.g. :c:type:`struct device <device>`).  That will
cause sphinx to generate a proper reference to the data type in
question (struct device in the example above) and "struct name"
will work as the link in the HTML output.

Fix device.rst by using that convention where applicable.

Fixes: 730c4c05 (PM / sleep / docs: Convert PM notifiers document to reST)
Signed-off-by: NRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Documentation shouldn't have broken links.
sphinx linkcheck builder scans all documents for external links, tries
to open them with urllib2, and writes an overview which ones are broken
and redirected to standard output and to output.txt in the output
directory.
Reviewed-by: NJani Nikula <jani.nikula@intel.com>
Tested-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NRémy Léone <remy.leone@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

A Japanese translation file contained the incorrect email address for
the linux-api list.
Signed-off-by: NTyler Hicks <tyhicks@canonical.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fix a se for so typo.
Signed-off-by: NJim Davis <jim.epost@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add documentation of -DCONFIG_SPARSE_RCU_POINTER.
I started to add documentation of -D__CHECK_ENDIAN__ as well, but
discovered I'm too late; that's now enabled by default.
Signed-off-by: NMatthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Silence the "make[1]: Nothing to be done for ..." messages for the
no-op targets in Makefile.sphinx.
Signed-off-by: NJim Davis <jim.epost@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Fixed spelling issue.
Signed-off-by: NNathan Howard <adanhawthorn@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The UAPI header split failed to update the documentation for the input
event codes; fix things accordingly.
Signed-off-by: NMartin Kepplinger <martink@posteo.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

It had gone stale, of course, as it would every year, a single date doesn't
really cover things, and the date isn't really needed anyway.

An extra space in the wrong place made Sphinx unhappy; take it out.
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Move the document describing PM notifiers (used during system sleep
state transitions) to Documentation/driver-api/pm/, convert it to reST
and update it to use current terminology.  Also replace the remaining
references to the old version of it in .txt documents with references
to the new one.
Signed-off-by: NRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Move the document describing the system sleep state transitions API
for devices to Documentation/driver-api/pm/, convert it to reST and
update it to use current terminology.  Also remove the remaining
reference to the old version of it from pm.h.

The new document still contains references to some documents in the
.txt format that will be converted later.
Signed-off-by: NRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Refresh the struct dev_pm_ops kerneldoc comment, so that it looks
better and is more readable after processing by Sphinx, and drop
the kerneldoc marker from a few other comments ("PM_EVENT_ messages"
and a couple of enum types declarations) which are not proper
kerneldoc and generally confuse Sphinx.

Also change the comment describing struct dev_pm_domain into
a kerneldoc one.
Signed-off-by: NRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Ben writes: "This series fixes some bugs I found in the new doc build system."

In any case where we recurse but don't mention $(MAKE) literally in
the recipe, we need to add a '+' at the start of the command to ensure
that parallel makes and various other options work properly.

Fixes: 609afe6b ("Documentation/sphinx: build the media intermediate ...")
Tested-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

As we use redirection to create the SVG file, even a failed conversion
will create the file and 'make' will consider it up-to-date if the
build is retried.  We should delete it in case of failure.

Fixes: ec868e4e ("docs-rst: media: build SVG from graphviz files")
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

As $(SHELL) doesn't include the -e option, any loop or other sequence
needs to include explicit checks for failing commands.

Fixes: 609afe6b ("Documentation/sphinx: build the media intermediate ...")
Fixes: 606b9ac8 ("doc-rst: generic way to build only sphinx sub-folders")
Fixes: cd21379b ("doc-rst: generic way to build PDF of sub-folders")
Tested-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NBen Hutchings <ben@decadent.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Make targets that don't depend on Sphinx work without warnings about
missing Sphinx. 'make cleandocs' will work without Sphinx just fine, and
the targets that are no-ops for Sphinx should just be skipped. Move them
outside of the HAVE_SPHINX checks to take precedence over the .DEFAULT
target for HAVE_SPHINX=0.
Reported-by: NJim Davis <jim.epost@gmail.com>
Reference: http://lkml.kernel.org/r/CA+r1ZhjRVqkjPXGOGB_BOAX2Hkfb+qQCtTzFfBMFeH1Mfeej7w@mail.gmail.comSigned-off-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The cleandocs target won't work if I use a different output folder::

  $ make O=/tmp/kernel SPHINXDIRS="process" cleandocs
  make[1]: Entering directory '/tmp/kernel'
  make[3]: *** No rule to make target 'clean'.  Stop.
  ... Documentation/Makefile.sphinx:100: recipe for target 'cleandocs' failed
Signed-off-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Use PYTHONDONTWRITEBYTECODE=1 to prevent python from creating .pyc files
in the source tree. Python 3.2 has a __pycache__ scheme [1], but before
that the only alternative seems to be to copy the source files to the
build tree to ensure the .pyc files are created there too. Just prevent
.pyc file generation for simplicity.

Considering the small amount of python code to compile (assuming sphinx
itself has .pyc around), the impact on build is neglible.

[1] http://stackoverflow.com/questions/3522079/changing-the-directory-where-pyc-files-are-created

References: http://lkml.kernel.org/r/CAMuHMdVxqpH7-9XJ+YE_pgoA+-fe0969cSkOehYh3uubYcrhZA@mail.gmail.comReported-by: NGeert Uytterhoeven <geert@linux-m68k.org>
References: http://lkml.kernel.org/r/1485816692.2900.17.camel@decadent.org.ukReported-by: NBen Hutchings <ben@decadent.org.uk>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

A fairly straightforward conversion to RST; the document is then added to
the driver-api manual.

Of course, this document has seen no substantive changes since 2008, so
chances are it needs work in other areas as well.

Cc: Mark Brown <broonie@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Convert deviceiobook.tmpl to RST and incorporate it into the driver API
manual.

Like the rest of our documentation, this one could use some work.  There's
no mention of ioremap() and friends, no mention of io_read*() and friends.
But we have nice documentation for all those folks writing new drivers that
do port I/O :).

The :c:func: notation has been left off of all the read*/write* functions.
There's no kerneldoc comments for them anyway, so those links will never be
live, and writing a bunch of repetitive "read a byte from I/O memory"
comments lacks appeal.

Cc: Matthew Wilcox <willy@infradead.org>
Cc: Alan Cox <gnomes@lxorguk.ukuu.org.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Tested by the command:

    make htmldocs

During the compiling process, zh_CN/coding-style.rst has no errors and
warnings generated, the generated html document has been checked.
Signed-off-by: NAndy Deng <theandy.deng@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies all changes from the English version, and should
be able to work with the documentation build system.
Signed-off-by: NAndy Deng <theandy.deng@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Some of the sentences in Chapters 19 and 20 are re-translated:

- Fixed translation errors in Section 2 of Chapter 19 to prevent
  misleading readers;
- Retranslate some sentences to make the translation more clear and
  accurate.
Signed-off-by: NAndy Deng <theandy.deng@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch fix some double words found in Documentation.
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Clearly nobody ever tried to build the documentation for the radix tree
before:

include/linux/radix-tree.h:400: warning: cannot understand function
prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter,
unsigned long start) '

Indeed, the regexes only handled a single '*', not one-or-more.  I have
tried to fix that, but now I have perl regexes all over my hands, and
I fear I shall never be clean again.
Signed-off-by: NMatthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Two of the example command lines use an argument to echo of "-c" which
isn't valid in (most versions of) echo causing these examples to fail.
Correct the argument to "-n" which works correctly.
Signed-off-by: NSteven Price <steven@ecrips.co.uk>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a bunch of entries reflective of programs that the kernel build:
sortextable, dtc. And while at it, expand the lex*.c entries to cover
e.g: dtc-lexer.c. Finally, exclude devicetable-offsets.h
Signed-off-by: NFlorian Fainelli <f.fainelli@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This looks like it was accidentally caught up in e21a05cb (doc:
cpuset: Update the cpuset flag file, 2010-02-24).

While I'm touching the line, also fix the posessive "cpusets" ->
"cpuset's".
Signed-off-by: NW. Trevor King <wking@tremily.us>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

... and a minor missing period at EOL
Signed-off-by: NSanjeev Gupta <ghane0@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Documentation for array parameters passed in a function, like the first
argument in the function below, weren't getting exported in the rst
format, although they work fine for html and pdf formats:

  void drm_clflush_pages(struct page * pages[], unsigned long num_pages)

That's because the string key to store the description in the
parameterdescs dictionary doesn't have the [] suffix.  This cleans up
the suffix from the key before accessing the dictionary.
Signed-off-by: NGabriel Krisman Bertazi <krisman@collabora.co.uk>
Fixes: c0d1b6ee ("kernel-doc: produce RestructuredText output")
Reviewed-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The current CPU hotplug is outdated. During the update to what we
currently have I rewrote it partly and moved to sphinx format.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Cc: Srivatsa Vaddagiri <vatsa@in.ibm.com>
Cc: Ashok Raj <ashok.raj@intel.com>
Cc: Joel Schopp <jschopp@austin.ibm.com>
Cc: linux-doc@vger.kernel.org
Signed-off-by: NSebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

$type_struct_full and friends are only used by the restructuredText
backend, because it needs to separate enum/struct/typedef/union from
the name of the type.  However, $type_struct is *also* used by the rST
backend.  This is confusing.

This patch replaces $type_struct's use in the rST backend with a new
$type_fallback; it modifies $type_struct so that it can be used in the
rST backend; and creates regular expressions like $type_struct
for enum/typedef/union, for use in all backends.

Note that, compared to $type_*_full, in the new regexes $1 includes both
the "kind" and the name (before, $1 was pretty much a constant).
Signed-off-by: NPaolo Bonzini <pbonzini@redhat.com>
Acked-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Note that, in order to produce the correct Docbook markup, the "." or "->"
must be separated from the member name in the regex's captured fields.  For
consistency, this change is applied to $type_member and $type_member_func
too, not just to $type_member_xml.

List mode only prints the struct name, to avoid any undesired change in
the operation of docproc.
Signed-off-by: NPaolo Bonzini <pbonzini@redhat.com>
Acked-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The restructuredText output includes both the parameter type and
the name for functions and function-typed members.  Do the same
for docbook.
Signed-off-by: NPaolo Bonzini <pbonzini@redhat.com>
Acked-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

An inline function can have an attribute, as in include/linux/log2.h,
and kernel-doc handles this already for simple cases.  However,
some attributes have arguments (e.g. the "target" attribute).
Handle those too.

Furthermore, attributes could be at the beginning of a function
declaration, before the return type.  To correctly handle this case,
you need to strip spaces after the attributes; otherwise, dump_function
is left confused.
Signed-off-by: NPaolo Bonzini <pbonzini@redhat.com>
Acked-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>