提交 1dc4bbf0 编写于 作者: M Mauro Carvalho Chehab 提交者: Jonathan Corbet

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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>
上级 726d661f
......@@ -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',
......
# -*- 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'),
]
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.
.. _doc_guide:
=================================
How to write kernel documentation
=================================
.. toctree::
:maxdepth: 1
sphinx.rst
kernel-doc.rst
docbook.rst
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
=================================
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.
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
------------------------
......
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 风格 “// ...” 注释。
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册