Merge branch 'doc/4.9' into docs-next

This commit is contained in:
Jonathan Corbet 2016-08-22 15:40:38 -06:00
commit 8d8f60c5e0
9 changed files with 178 additions and 20 deletions

View File

@ -72,6 +72,7 @@ installmandocs: mandocs
# no-op for the DocBook toolchain
epubdocs:
latexdocs:
###
#External programs used

View File

@ -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'

View File

@ -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}
'''
}

View File

@ -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
-----------

View File

@ -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

View File

@ -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.

View File

@ -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,
}

View File

@ -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

View File

@ -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;