docs-rst: doc-guide: split the kernel-documentation.rst contents
Having the kernel-documentation at the topmost level doesn't allow generating a separate PDF file for it. Also, makes harder to add extra contents. So, place it on a sub-dir. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>hifive-unleashed-5.1
Mauro Carvalho Chehab
Jonathan Corbet
parent
726d661fea
commit
1dc4bbf0b2
|
|
@ -258,7 +258,7 @@ kdump/
|
|||
- directory with mini HowTo on getting the crash dump code to work.
|
||||
process/kernel-docs.rst
|
||||
- listing of various WWW + books that document kernel internals.
|
||||
kernel-documentation.rst
|
||||
doc-guide/
|
||||
- how to write and format reStructuredText kernel documentation
|
||||
admin-guide/kernel-parameters.rst
|
||||
- summary listing of command line / boot prompt args for the kernel.
|
||||
|
|
|
|||
|
|
@ -340,6 +340,8 @@ if major == 1 and minor > 3:
|
|||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
|
||||
'The kernel development community', 'manual'),
|
||||
('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
|
||||
'The kernel development community', 'manual'),
|
||||
('core-api/index', 'core-api.tex', 'The kernel core API manual',
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
# -*- coding: utf-8; mode: python -*-
|
||||
|
||||
project = 'Linux Kernel Documentation Guide'
|
||||
|
||||
tags.add("subproject")
|
||||
|
||||
latex_documents = [
|
||||
('index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
|
||||
'The kernel development community', 'manual'),
|
||||
]
|
||||
|
|
@ -0,0 +1,90 @@
|
|||
DocBook XML [DEPRECATED]
|
||||
========================
|
||||
|
||||
.. attention::
|
||||
|
||||
This section describes the deprecated DocBook XML toolchain. Please do not
|
||||
create new DocBook XML template files. Please consider converting existing
|
||||
DocBook XML templates files to Sphinx/reStructuredText.
|
||||
|
||||
Converting DocBook to Sphinx
|
||||
----------------------------
|
||||
|
||||
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
|
||||
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
|
||||
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
|
||||
which uses ``pandoc`` under the hood. For example::
|
||||
|
||||
$ cd Documentation/sphinx
|
||||
$ ./tmplcvt ../DocBook/in.tmpl ../out.rst
|
||||
|
||||
Then edit the resulting rst files to fix any remaining issues, and add the
|
||||
document in the ``toctree`` in ``Documentation/index.rst``.
|
||||
|
||||
Components of the kernel-doc system
|
||||
-----------------------------------
|
||||
|
||||
Many places in the source tree have extractable documentation in the form of
|
||||
block comments above functions. The components of this system are:
|
||||
|
||||
- ``scripts/kernel-doc``
|
||||
|
||||
This is a perl script that hunts for the block comments and can mark them up
|
||||
directly into reStructuredText, DocBook, man, text, and HTML. (No, not
|
||||
texinfo.)
|
||||
|
||||
- ``Documentation/DocBook/*.tmpl``
|
||||
|
||||
These are XML template files, which are normal XML files with special
|
||||
place-holders for where the extracted documentation should go.
|
||||
|
||||
- ``scripts/docproc.c``
|
||||
|
||||
This is a program for converting XML template files into XML files. When a
|
||||
file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
|
||||
able to distinguish between internal and external functions.
|
||||
|
||||
It invokes kernel-doc, giving it the list of functions that are to be
|
||||
documented.
|
||||
|
||||
Additionally it is used to scan the XML template files to locate all the files
|
||||
referenced herein. This is used to generate dependency information as used by
|
||||
make.
|
||||
|
||||
- ``Makefile``
|
||||
|
||||
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
|
||||
DocBook XML files, PostScript files, PDF files, and html files in
|
||||
Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
|
||||
|
||||
- ``Documentation/DocBook/Makefile``
|
||||
|
||||
This is where C files are associated with SGML templates.
|
||||
|
||||
How to use kernel-doc comments in DocBook XML template files
|
||||
------------------------------------------------------------
|
||||
|
||||
DocBook XML template files (\*.tmpl) are like normal XML files, except that they
|
||||
can contain escape sequences where extracted documentation should be inserted.
|
||||
|
||||
``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
|
||||
functions that are exported using ``EXPORT_SYMBOL``: the function list is
|
||||
collected from files listed in ``Documentation/DocBook/Makefile``.
|
||||
|
||||
``!I<filename>`` is replaced by the documentation for functions that are **not**
|
||||
exported using ``EXPORT_SYMBOL``.
|
||||
|
||||
``!D<filename>`` is used to name additional files to search for functions
|
||||
exported using ``EXPORT_SYMBOL``.
|
||||
|
||||
``!F<filename> <function [functions...]>`` is replaced by the documentation, in
|
||||
``<filename>``, for the functions listed.
|
||||
|
||||
``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
|
||||
section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
|
||||
``<section title>``; do not quote the ``<section title>``.
|
||||
|
||||
``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
|
||||
sections and documented functions, symbols, etc. are used. This makes sense to
|
||||
use when you use ``!F`` or ``!P`` only and want to verify that all documentation
|
||||
is included.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
.. _doc_guide:
|
||||
|
||||
=================================
|
||||
How to write kernel documentation
|
||||
=================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
sphinx.rst
|
||||
kernel-doc.rst
|
||||
docbook.rst
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
Indices
|
||||
=======
|
||||
|
||||
* :ref:`genindex`
|
||||
|
|
@ -1,228 +1,3 @@
|
|||
=================================
|
||||
How to write kernel documentation
|
||||
=================================
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The Linux kernel uses `Sphinx`_ to generate pretty documentation from
|
||||
`reStructuredText`_ files under ``Documentation``. To build the documentation in
|
||||
HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
|
||||
documentation is placed in ``Documentation/output``.
|
||||
|
||||
.. _Sphinx: http://www.sphinx-doc.org/
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
|
||||
The reStructuredText files may contain directives to include structured
|
||||
documentation comments, or kernel-doc comments, from source files. Usually these
|
||||
are used to describe the functions and types and design of the code. The
|
||||
kernel-doc comments have some special structure and formatting, but beyond that
|
||||
they are also treated as reStructuredText.
|
||||
|
||||
There is also the deprecated DocBook toolchain to generate documentation from
|
||||
DocBook XML template files under ``Documentation/DocBook``. The DocBook files
|
||||
are to be converted to reStructuredText, and the toolchain is slated to be
|
||||
removed.
|
||||
|
||||
Finally, there are thousands of plain text documentation files scattered around
|
||||
``Documentation``. Some of these will likely be converted to reStructuredText
|
||||
over time, but the bulk of them will remain in plain text.
|
||||
|
||||
Sphinx Build
|
||||
============
|
||||
|
||||
The usual way to generate the documentation is to run ``make htmldocs`` or
|
||||
``make pdfdocs``. There are also other formats available, see the documentation
|
||||
section of ``make help``. The generated documentation is placed in
|
||||
format-specific subdirectories under ``Documentation/output``.
|
||||
|
||||
To generate documentation, Sphinx (``sphinx-build``) must obviously be
|
||||
installed. For prettier HTML output, the Read the Docs Sphinx theme
|
||||
(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also
|
||||
needed. All of these are widely available and packaged in distributions.
|
||||
|
||||
To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
|
||||
variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
|
||||
output.
|
||||
|
||||
To remove the generated documentation, run ``make cleandocs``.
|
||||
|
||||
Writing Documentation
|
||||
=====================
|
||||
|
||||
Adding new documentation can be as simple as:
|
||||
|
||||
1. Add a new ``.rst`` file somewhere under ``Documentation``.
|
||||
2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
|
||||
|
||||
.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
|
||||
|
||||
This is usually good enough for simple documentation (like the one you're
|
||||
reading right now), but for larger documents it may be advisable to create a
|
||||
subdirectory (or use an existing one). For example, the graphics subsystem
|
||||
documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
|
||||
and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
|
||||
the main index.
|
||||
|
||||
See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
|
||||
with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
|
||||
to get started with reStructuredText. There are also some `Sphinx specific
|
||||
markup constructs`_.
|
||||
|
||||
.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
|
||||
.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
|
||||
|
||||
Specific guidelines for the kernel documentation
|
||||
------------------------------------------------
|
||||
|
||||
Here are some specific guidelines for the kernel documentation:
|
||||
|
||||
* Please don't go overboard with reStructuredText markup. Keep it simple.
|
||||
|
||||
* Please stick to this order of heading adornments:
|
||||
|
||||
1. ``=`` with overline for document title::
|
||||
|
||||
==============
|
||||
Document title
|
||||
==============
|
||||
|
||||
2. ``=`` for chapters::
|
||||
|
||||
Chapters
|
||||
========
|
||||
|
||||
3. ``-`` for sections::
|
||||
|
||||
Section
|
||||
-------
|
||||
|
||||
4. ``~`` for subsections::
|
||||
|
||||
Subsection
|
||||
~~~~~~~~~~
|
||||
|
||||
Although RST doesn't mandate a specific order ("Rather than imposing a fixed
|
||||
number and order of section title adornment styles, the order enforced will be
|
||||
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
|
||||
-----------
|
||||
|
||||
We recommend the use of *list table* formats. The *list table* formats are
|
||||
double-stage lists. Compared to the ASCII-art they might not be as
|
||||
comfortable for
|
||||
readers of the text files. Their advantage is that they are easy to
|
||||
create or modify and that the diff of a modification is much more meaningful,
|
||||
because it is limited to the modified content.
|
||||
|
||||
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 automatically inserts (empty)
|
||||
cells instead of spanning the last cell.
|
||||
|
||||
options:
|
||||
|
||||
* ``:header-rows:`` [int] count of header rows
|
||||
* ``:stub-columns:`` [int] count of stub columns
|
||||
* ``:widths:`` [[int] [int] ... ] widths of columns
|
||||
* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
|
||||
|
||||
roles:
|
||||
|
||||
* ``:cspan:`` [int] additional columns (*morecols*)
|
||||
* ``:rspan:`` [int] additional rows (*morerows*)
|
||||
|
||||
The example below shows how to use this markup. The first level of the staged
|
||||
list is the *table-row*. In the *table-row* there is only one markup allowed,
|
||||
the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
|
||||
and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
|
||||
<last row>`).
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. flat-table:: table title
|
||||
:widths: 2 1 1 3
|
||||
|
||||
* - head col 1
|
||||
- head col 2
|
||||
- head col 3
|
||||
- head col 4
|
||||
|
||||
* - column 1
|
||||
- field 1.1
|
||||
- field 1.2 with autospan
|
||||
|
||||
* - column 2
|
||||
- field 2.1
|
||||
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
|
||||
|
||||
* .. _`last row`:
|
||||
|
||||
- column 3
|
||||
|
||||
Rendered as:
|
||||
|
||||
.. flat-table:: table title
|
||||
:widths: 2 1 1 3
|
||||
|
||||
* - head col 1
|
||||
- head col 2
|
||||
- head col 3
|
||||
- head col 4
|
||||
|
||||
* - column 1
|
||||
- field 1.1
|
||||
- field 1.2 with autospan
|
||||
|
||||
* - column 2
|
||||
- field 2.1
|
||||
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
|
||||
|
||||
* .. _`last row`:
|
||||
|
||||
- column 3
|
||||
|
||||
|
||||
Including kernel-doc comments
|
||||
=============================
|
||||
|
||||
|
|
@ -586,94 +361,3 @@ file.
|
|||
|
||||
Data structures visible in kernel include files should also be documented using
|
||||
kernel-doc formatted comments.
|
||||
|
||||
DocBook XML [DEPRECATED]
|
||||
========================
|
||||
|
||||
.. attention::
|
||||
|
||||
This section describes the deprecated DocBook XML toolchain. Please do not
|
||||
create new DocBook XML template files. Please consider converting existing
|
||||
DocBook XML templates files to Sphinx/reStructuredText.
|
||||
|
||||
Converting DocBook to Sphinx
|
||||
----------------------------
|
||||
|
||||
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
|
||||
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
|
||||
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
|
||||
which uses ``pandoc`` under the hood. For example::
|
||||
|
||||
$ cd Documentation/sphinx
|
||||
$ ./tmplcvt ../DocBook/in.tmpl ../out.rst
|
||||
|
||||
Then edit the resulting rst files to fix any remaining issues, and add the
|
||||
document in the ``toctree`` in ``Documentation/index.rst``.
|
||||
|
||||
Components of the kernel-doc system
|
||||
-----------------------------------
|
||||
|
||||
Many places in the source tree have extractable documentation in the form of
|
||||
block comments above functions. The components of this system are:
|
||||
|
||||
- ``scripts/kernel-doc``
|
||||
|
||||
This is a perl script that hunts for the block comments and can mark them up
|
||||
directly into reStructuredText, DocBook, man, text, and HTML. (No, not
|
||||
texinfo.)
|
||||
|
||||
- ``Documentation/DocBook/*.tmpl``
|
||||
|
||||
These are XML template files, which are normal XML files with special
|
||||
place-holders for where the extracted documentation should go.
|
||||
|
||||
- ``scripts/docproc.c``
|
||||
|
||||
This is a program for converting XML template files into XML files. When a
|
||||
file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
|
||||
able to distinguish between internal and external functions.
|
||||
|
||||
It invokes kernel-doc, giving it the list of functions that are to be
|
||||
documented.
|
||||
|
||||
Additionally it is used to scan the XML template files to locate all the files
|
||||
referenced herein. This is used to generate dependency information as used by
|
||||
make.
|
||||
|
||||
- ``Makefile``
|
||||
|
||||
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
|
||||
DocBook XML files, PostScript files, PDF files, and html files in
|
||||
Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
|
||||
|
||||
- ``Documentation/DocBook/Makefile``
|
||||
|
||||
This is where C files are associated with SGML templates.
|
||||
|
||||
How to use kernel-doc comments in DocBook XML template files
|
||||
------------------------------------------------------------
|
||||
|
||||
DocBook XML template files (\*.tmpl) are like normal XML files, except that they
|
||||
can contain escape sequences where extracted documentation should be inserted.
|
||||
|
||||
``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
|
||||
functions that are exported using ``EXPORT_SYMBOL``: the function list is
|
||||
collected from files listed in ``Documentation/DocBook/Makefile``.
|
||||
|
||||
``!I<filename>`` is replaced by the documentation for functions that are **not**
|
||||
exported using ``EXPORT_SYMBOL``.
|
||||
|
||||
``!D<filename>`` is used to name additional files to search for functions
|
||||
exported using ``EXPORT_SYMBOL``.
|
||||
|
||||
``!F<filename> <function [functions...]>`` is replaced by the documentation, in
|
||||
``<filename>``, for the functions listed.
|
||||
|
||||
``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
|
||||
section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
|
||||
``<section title>``; do not quote the ``<section title>``.
|
||||
|
||||
``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
|
||||
sections and documented functions, symbols, etc. are used. This makes sense to
|
||||
use when you use ``!F`` or ``!P`` only and want to verify that all documentation
|
||||
is included.
|
||||
|
|
@ -0,0 +1,219 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
The Linux kernel uses `Sphinx`_ to generate pretty documentation from
|
||||
`reStructuredText`_ files under ``Documentation``. To build the documentation in
|
||||
HTML or PDF formats, use ``make htmldocs`` or ``make pdfdocs``. The generated
|
||||
documentation is placed in ``Documentation/output``.
|
||||
|
||||
.. _Sphinx: http://www.sphinx-doc.org/
|
||||
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
||||
|
||||
The reStructuredText files may contain directives to include structured
|
||||
documentation comments, or kernel-doc comments, from source files. Usually these
|
||||
are used to describe the functions and types and design of the code. The
|
||||
kernel-doc comments have some special structure and formatting, but beyond that
|
||||
they are also treated as reStructuredText.
|
||||
|
||||
There is also the deprecated DocBook toolchain to generate documentation from
|
||||
DocBook XML template files under ``Documentation/DocBook``. The DocBook files
|
||||
are to be converted to reStructuredText, and the toolchain is slated to be
|
||||
removed.
|
||||
|
||||
Finally, there are thousands of plain text documentation files scattered around
|
||||
``Documentation``. Some of these will likely be converted to reStructuredText
|
||||
over time, but the bulk of them will remain in plain text.
|
||||
|
||||
Sphinx Build
|
||||
============
|
||||
|
||||
The usual way to generate the documentation is to run ``make htmldocs`` or
|
||||
``make pdfdocs``. There are also other formats available, see the documentation
|
||||
section of ``make help``. The generated documentation is placed in
|
||||
format-specific subdirectories under ``Documentation/output``.
|
||||
|
||||
To generate documentation, Sphinx (``sphinx-build``) must obviously be
|
||||
installed. For prettier HTML output, the Read the Docs Sphinx theme
|
||||
(``sphinx_rtd_theme``) is used if available. For PDF output, ``rst2pdf`` is also
|
||||
needed. All of these are widely available and packaged in distributions.
|
||||
|
||||
To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
|
||||
variable. For example, use ``make SPHINXOPTS=-v htmldocs`` to get more verbose
|
||||
output.
|
||||
|
||||
To remove the generated documentation, run ``make cleandocs``.
|
||||
|
||||
Writing Documentation
|
||||
=====================
|
||||
|
||||
Adding new documentation can be as simple as:
|
||||
|
||||
1. Add a new ``.rst`` file somewhere under ``Documentation``.
|
||||
2. Refer to it from the Sphinx main `TOC tree`_ in ``Documentation/index.rst``.
|
||||
|
||||
.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
|
||||
|
||||
This is usually good enough for simple documentation (like the one you're
|
||||
reading right now), but for larger documents it may be advisable to create a
|
||||
subdirectory (or use an existing one). For example, the graphics subsystem
|
||||
documentation is under ``Documentation/gpu``, split to several ``.rst`` files,
|
||||
and has a separate ``index.rst`` (with a ``toctree`` of its own) referenced from
|
||||
the main index.
|
||||
|
||||
See the documentation for `Sphinx`_ and `reStructuredText`_ on what you can do
|
||||
with them. In particular, the Sphinx `reStructuredText Primer`_ is a good place
|
||||
to get started with reStructuredText. There are also some `Sphinx specific
|
||||
markup constructs`_.
|
||||
|
||||
.. _reStructuredText Primer: http://www.sphinx-doc.org/en/stable/rest.html
|
||||
.. _Sphinx specific markup constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
|
||||
|
||||
Specific guidelines for the kernel documentation
|
||||
------------------------------------------------
|
||||
|
||||
Here are some specific guidelines for the kernel documentation:
|
||||
|
||||
* Please don't go overboard with reStructuredText markup. Keep it simple.
|
||||
|
||||
* Please stick to this order of heading adornments:
|
||||
|
||||
1. ``=`` with overline for document title::
|
||||
|
||||
==============
|
||||
Document title
|
||||
==============
|
||||
|
||||
2. ``=`` for chapters::
|
||||
|
||||
Chapters
|
||||
========
|
||||
|
||||
3. ``-`` for sections::
|
||||
|
||||
Section
|
||||
-------
|
||||
|
||||
4. ``~`` for subsections::
|
||||
|
||||
Subsection
|
||||
~~~~~~~~~~
|
||||
|
||||
Although RST doesn't mandate a specific order ("Rather than imposing a fixed
|
||||
number and order of section title adornment styles, the order enforced will be
|
||||
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
|
||||
-----------
|
||||
|
||||
We recommend the use of *list table* formats. The *list table* formats are
|
||||
double-stage lists. Compared to the ASCII-art they might not be as
|
||||
comfortable for
|
||||
readers of the text files. Their advantage is that they are easy to
|
||||
create or modify and that the diff of a modification is much more meaningful,
|
||||
because it is limited to the modified content.
|
||||
|
||||
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 automatically inserts (empty)
|
||||
cells instead of spanning the last cell.
|
||||
|
||||
options:
|
||||
|
||||
* ``:header-rows:`` [int] count of header rows
|
||||
* ``:stub-columns:`` [int] count of stub columns
|
||||
* ``:widths:`` [[int] [int] ... ] widths of columns
|
||||
* ``:fill-cells:`` instead of auto-spanning missing cells, insert missing cells
|
||||
|
||||
roles:
|
||||
|
||||
* ``:cspan:`` [int] additional columns (*morecols*)
|
||||
* ``:rspan:`` [int] additional rows (*morerows*)
|
||||
|
||||
The example below shows how to use this markup. The first level of the staged
|
||||
list is the *table-row*. In the *table-row* there is only one markup allowed,
|
||||
the list of the cells in this *table-row*. Exceptions are *comments* ( ``..`` )
|
||||
and *targets* (e.g. a ref to ``:ref:`last row <last row>``` / :ref:`last row
|
||||
<last row>`).
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. flat-table:: table title
|
||||
:widths: 2 1 1 3
|
||||
|
||||
* - head col 1
|
||||
- head col 2
|
||||
- head col 3
|
||||
- head col 4
|
||||
|
||||
* - column 1
|
||||
- field 1.1
|
||||
- field 1.2 with autospan
|
||||
|
||||
* - column 2
|
||||
- field 2.1
|
||||
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
|
||||
|
||||
* .. _`last row`:
|
||||
|
||||
- column 3
|
||||
|
||||
Rendered as:
|
||||
|
||||
.. flat-table:: table title
|
||||
:widths: 2 1 1 3
|
||||
|
||||
* - head col 1
|
||||
- head col 2
|
||||
- head col 3
|
||||
- head col 4
|
||||
|
||||
* - column 1
|
||||
- field 1.1
|
||||
- field 1.2 with autospan
|
||||
|
||||
* - column 2
|
||||
- field 2.1
|
||||
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
|
||||
|
||||
* .. _`last row`:
|
||||
|
||||
- column 3
|
||||
|
|
@ -38,7 +38,7 @@ merged much easier.
|
|||
|
||||
process/index
|
||||
dev-tools/index
|
||||
kernel-documentation
|
||||
doc-guide/index
|
||||
|
||||
Kernel API documentation
|
||||
------------------------
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
NOTE: this document is outdated and will eventually be removed. See
|
||||
Documentation/kernel-documentation.rst for current information.
|
||||
Documentation/doc-guide/ for current information.
|
||||
|
||||
kernel-doc nano-HOWTO
|
||||
=====================
|
||||
|
|
|
|||
|
|
@ -358,8 +358,8 @@ them, as appropriate, for externally-available functions. Even in areas
|
|||
which have not been so documented, there is no harm in adding kerneldoc
|
||||
comments for the future; indeed, this can be a useful activity for
|
||||
beginning kernel developers. The format of these comments, along with some
|
||||
information on how to create kerneldoc templates can be found in the file
|
||||
Documentation/kernel-documentation.rst.
|
||||
information on how to create kerneldoc templates can be found at
|
||||
:ref:`Documentation/doc-guide/ <doc_guide>`.
|
||||
|
||||
Anybody who reads through a significant amount of existing kernel code will
|
||||
note that, often, comments are most notable by their absence. Once again,
|
||||
|
|
|
|||
|
|
@ -525,8 +525,8 @@ of the function, telling people what it does, and possibly WHY it does
|
|||
it.
|
||||
|
||||
When commenting the kernel API functions, please use the kernel-doc format.
|
||||
See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
|
||||
for details.
|
||||
See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
|
||||
``scripts/kernel-doc`` for details.
|
||||
|
||||
The preferred style for long (multi-line) comments is:
|
||||
|
||||
|
|
|
|||
|
|
@ -399,7 +399,7 @@ C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pasca
|
|||
些事情的原因。
|
||||
|
||||
当注释内核API函数时，请使用 kernel-doc 格式。请看
|
||||
Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
|
||||
Documentation/doc-guide/和scripts/kernel-doc 以获得详细信息。
|
||||
|
||||
Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue