summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Documentation/DocBook/Makefile1
-rw-r--r--Documentation/Makefile.sphinx7
-rw-r--r--Documentation/conf.py47
-rw-r--r--Documentation/kernel-documentation.rst29
-rw-r--r--Documentation/media/uapi/cec/cec-func-open.rst2
-rw-r--r--Documentation/media/uapi/cec/cec-ioc-dqevent.rst5
-rw-r--r--Documentation/sphinx/cdomain.py102
-rw-r--r--Makefile2
-rwxr-xr-xscripts/kernel-doc3
9 files changed, 178 insertions, 20 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index a91c96522379..a558dfcc9e2d 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -72,6 +72,7 @@ installmandocs: mandocs
# no-op for the DocBook toolchain
epubdocs:
+latexdocs:
###
#External programs used
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ba4efb1f68f3..894cfaa41f55 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -66,12 +66,16 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4);
htmldocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
-pdfdocs:
+latexdocs:
ifeq ($(HAVE_PDFLATEX),0)
$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_PDFLATEX
@$(call loop_cmd,sphinx,latex,.,latex,.)
+endif # HAVE_PDFLATEX
+
+pdfdocs: latexdocs
+ifneq ($(HAVE_PDFLATEX),0)
$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex
endif # HAVE_PDFLATEX
@@ -95,6 +99,7 @@ endif # HAVE_SPHINX
dochelp:
@echo ' Linux kernel internal documentation in different formats (Sphinx):'
@echo ' htmldocs - HTML'
+ @echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 39b9c4a26f6e..46e69dba0e3c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -34,7 +34,7 @@ from load_config import loadConfig
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include']
+extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain']
# The name of the math extension changed on Sphinx 1.4
if minor > 3:
@@ -277,26 +277,46 @@ latex_elements = {
% Allow generate some pages in landscape
\\usepackage{lscape}
- % Put notes in gray color and let them be inside a table
-
- \\definecolor{MyGray}{rgb}{0.80,0.80,0.80}
-
- \\makeatletter\\newenvironment{graybox}{%
- \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\columnwidth}}{\\end{minipage}\\end{lrbox}%
- \\colorbox{MyGray}{\\usebox{\\@tempboxa}}
+ % Put notes in color and let them be inside a table
+ \\definecolor{NoteColor}{RGB}{204,255,255}
+ \\definecolor{WarningColor}{RGB}{255,204,204}
+ \\definecolor{AttentionColor}{RGB}{255,255,204}
+ \\definecolor{OtherColor}{RGB}{204,204,204}
+ \\newlength{\\mynoticelength}
+ \\makeatletter\\newenvironment{coloredbox}[1]{%
+ \\setlength{\\fboxrule}{1pt}
+ \\setlength{\\fboxsep}{7pt}
+ \\setlength{\\mynoticelength}{\\linewidth}
+ \\addtolength{\\mynoticelength}{-2\\fboxsep}
+ \\addtolength{\\mynoticelength}{-2\\fboxrule}
+ \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}%
+ \\ifthenelse%
+ {\\equal{\\py@noticetype}{note}}%
+ {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}%
+ {%
+ \\ifthenelse%
+ {\\equal{\\py@noticetype}{warning}}%
+ {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}%
+ {%
+ \\ifthenelse%
+ {\\equal{\\py@noticetype}{attention}}%
+ {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
+ {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
+ }%
+ }%
}\\makeatother
\\makeatletter
- \\renewenvironment{notice}[2]{
- \\begin{graybox}
- \\bf\\it
+ \\renewenvironment{notice}[2]{%
\\def\\py@noticetype{#1}
+ \\begin{coloredbox}{#1}
+ \\bf\\it
\\par\\strong{#2}
\\csname py@noticestart@#1\\endcsname
}
{
\\csname py@noticeend@\\py@noticetype\\endcsname
- \\end{graybox}
+ \\end{coloredbox}
}
\\makeatother
@@ -306,6 +326,9 @@ latex_elements = {
\\setromanfont{DejaVu Sans}
\\setmonofont{DejaVu Sans Mono}
+ % To allow adjusting table sizes
+ \\usepackage{adjustbox}
+
'''
}
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 391decc66a18..a0dcae15639b 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation:
the order as encountered."), having the higher levels the same overall makes
it easier to follow the documents.
+
+the C domain
+------------
+
+The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
+function prototype:
+
+.. code-block:: rst
+
+ .. c:function:: int ioctl( int fd, int request )
+
+The C domain of the kernel-doc has some additional features. E.g. you can
+*rename* the reference name of a function with a common name like ``open`` or
+``ioctl``:
+
+.. code-block:: rst
+
+ .. 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:
+
+.. code-block:: rst
+
+ :c:func:`VIDIOC_LOG_STATUS`
+
+
list tables
-----------
diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst
index 38fd7e0cfccd..7c0f981a6e07 100644
--- a/Documentation/media/uapi/cec/cec-func-open.rst
+++ b/Documentation/media/uapi/cec/cec-func-open.rst
@@ -32,7 +32,7 @@ Arguments
Open flags. Access mode must be ``O_RDWR``.
When the ``O_NONBLOCK`` flag is given, the
- :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls
+ :ref:`CEC_RECEIVE <CEC_RECEIVE>` and :c:func:`CEC_DQEVENT` ioctls
will return the ``EAGAIN`` error code when no message or event is available, and
ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
:ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
index 7a6d6d00ce19..4e12e6cd88ee 100644
--- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
+++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst
@@ -15,7 +15,8 @@ CEC_DQEVENT - Dequeue a CEC event
Synopsis
========
-.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )
+.. c:function:: int ioctl( int fd, int request, struct cec_event *argp )
+ :name: CEC_DQEVENT
Arguments
=========
@@ -36,7 +37,7 @@ Description
and is currently only available as a staging kernel module.
CEC devices can send asynchronous events. These can be retrieved by
-calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in
+calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
non-blocking mode and no event is pending, then it will return -1 and
set errno to the ``EAGAIN`` error code.
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
new file mode 100644
index 000000000000..9eb714ada394
--- /dev/null
+++ b/Documentation/sphinx/cdomain.py
@@ -0,0 +1,102 @@
+# -*- coding: utf-8; mode: python -*-
+u"""
+ cdomain
+ ~~~~~~~
+
+ Replacement for the sphinx c-domain.
+
+ :copyright: Copyright (C) 2016 Markus Heiser
+ :license: GPL Version 2, June 1991 see Linux/COPYING for details.
+
+ List of customizations:
+
+ * Moved the *duplicate C object description* warnings for function
+ declarations in the nitpicky mode. See Sphinx documentation for
+ the config values for ``nitpick`` and ``nitpick_ignore``.
+
+ * 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 function is referenced by::
+
+ * :c:func:`VIDIOC_LOG_STATUS` or
+ * :any:`VIDIOC_LOG_STATUS` (``:any:`` needs sphinx 1.3)
+"""
+
+from docutils.parsers.rst import directives
+
+from sphinx.domains.c import CObject as Base_CObject
+from sphinx.domains.c import CDomain as Base_CDomain
+
+__version__ = '1.0'
+
+def setup(app):
+
+ app.override_domain(CDomain)
+
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
+
+class CObject(Base_CObject):
+
+ """
+ Description of a C language object.
+ """
+ option_spec = {
+ "name" : directives.unchanged
+ }
+
+ def handle_signature(self, sig, signode):
+ """Transform a C signature into RST nodes."""
+ fullname = super(CObject, self).handle_signature(sig, signode)
+ if "name" in self.options:
+ if self.objtype == 'function':
+ fullname = self.options["name"]
+ else:
+ # FIXME: handle :name: value of other declaration types?
+ pass
+ return fullname
+
+ def add_target_and_index(self, name, sig, signode):
+ # for C API items we add a prefix since names are usually not qualified
+ # by a module name and so easily clash with e.g. section titles
+ targetname = 'c.' + name
+ if targetname not in self.state.document.ids:
+ signode['names'].append(targetname)
+ signode['ids'].append(targetname)
+ signode['first'] = (not self.names)
+ self.state.document.note_explicit_target(signode)
+ inv = self.env.domaindata['c']['objects']
+ if (name in inv and self.env.config.nitpicky):
+ if self.objtype == 'function':
+ if ('c:func', name) not in self.env.config.nitpick_ignore:
+ self.state_machine.reporter.warning(
+ 'duplicate C object description of %s, ' % name +
+ 'other instance in ' + self.env.doc2path(inv[name][0]),
+ line=self.lineno)
+ inv[name] = (self.env.docname, self.objtype)
+
+ indextext = self.get_index_text(name)
+ if indextext:
+ self.indexnode['entries'].append(('single', indextext,
+ targetname, '', None))
+
+class CDomain(Base_CDomain):
+
+ """C language domain."""
+ name = 'c'
+ label = 'C'
+ directives = {
+ 'function': CObject,
+ 'member': CObject,
+ 'macro': CObject,
+ 'type': CObject,
+ 'var': CObject,
+ }
diff --git a/Makefile b/Makefile
index 70de1448c571..0fa3feb6f74e 100644
--- a/Makefile
+++ b/Makefile
@@ -1432,7 +1432,7 @@ $(help-board-dirs): help-%:
# Documentation targets
# ---------------------------------------------------------------------------
-DOC_TARGETS := xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs
+DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs
PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4f2e9049e8fa..ba081c7636a2 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1849,9 +1849,6 @@ sub output_function_rst(%) {
$count++;
$type = $args{'parametertypes'}{$parameter};
- # RST doesn't like address_space tags at function prototypes
- $type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
-
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
# pointer-to-function
print $1 . $parameter . ") (" . $2;