diff options
| -rw-r--r-- | Documentation/kernel-documentation.rst | 29 | ||||
| -rw-r--r-- | Documentation/sphinx/cdomain.py | 31 |
2 files changed, 60 insertions, 0 deletions
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index c4eb5049da390..bc4c3f5268161 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/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py index d6e66e2898084..b1912c80ff77a 100644 --- a/Documentation/sphinx/cdomain.py +++ b/Documentation/sphinx/cdomain.py @@ -7,8 +7,24 @@ u""" :copyright: Copyright (C) 2016 Markus Heiser :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + List of customizations: + + * 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 @@ -29,6 +45,21 @@ 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 + class CDomain(Base_CDomain): |