Merge branch 'mauro-doc' into docs-next
Jonathan Corbet
commit
ca9667fcc8
|
|
@ -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,20 @@
|
|||
.. _doc_guide:
|
||||
|
||||
=================================
|
||||
How to write kernel documentation
|
||||
=================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
sphinx.rst
|
||||
kernel-doc.rst
|
||||
parse-headers.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
|
||||
=============================
|
||||
|
||||
|
|
@ -591,94 +366,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,208 @@
|
|||
===========================
|
||||
Including uAPI header files
|
||||
===========================
|
||||
|
||||
Sometimes, it is useful to include header files and C example codes in
|
||||
order to describe the userspace API and to generate cross-references
|
||||
between the code and the documentation. Adding cross-references for
|
||||
userspace API files has an additional vantage: Sphinx will generate warnings
|
||||
if a symbol is not found at the documentation. That helps to keep the
|
||||
uAPI documentation in sync with the Kernel changes.
|
||||
The :ref:`parse_headers.pl <parse_headers>` provide a way to generate such
|
||||
cross-references. It has to be called via Makefile, while building the
|
||||
documentation. Please see ``Documentation/media/Makefile`` for an example
|
||||
about how to use it inside the Kernel tree.
|
||||
|
||||
.. _parse_headers:
|
||||
|
||||
parse_headers.pl
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. NOTE: the man pages below were generated using pod2rst tool:
|
||||
.. http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
|
||||
.. If you need to change anything below this point, please do the changes
|
||||
.. at parse-headers.pl directly, re-run the script and paste the output of
|
||||
.. the script here.
|
||||
|
||||
****
|
||||
NAME
|
||||
****
|
||||
|
||||
|
||||
parse_headers.pl - parse a C file, in order to identify functions, structs,
|
||||
enums and defines and create cross-references to a Sphinx book.
|
||||
|
||||
|
||||
********
|
||||
SYNOPSIS
|
||||
********
|
||||
|
||||
|
||||
\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
|
||||
|
||||
Where <options> can be: --debug, --help or --man.
|
||||
|
||||
|
||||
*******
|
||||
OPTIONS
|
||||
*******
|
||||
|
||||
|
||||
|
||||
\ **--debug**\
|
||||
|
||||
Put the script in verbose mode, useful for debugging.
|
||||
|
||||
|
||||
|
||||
\ **--help**\
|
||||
|
||||
Prints a brief help message and exits.
|
||||
|
||||
|
||||
|
||||
\ **--man**\
|
||||
|
||||
Prints the manual page and exits.
|
||||
|
||||
|
||||
|
||||
|
||||
***********
|
||||
DESCRIPTION
|
||||
***********
|
||||
|
||||
|
||||
Convert a C header or source file (C_FILE), into a ReStructured Text
|
||||
included via ..parsed-literal block with cross-references for the
|
||||
documentation files that describe the API. It accepts an optional
|
||||
EXCEPTIONS_FILE with describes what elements will be either ignored or
|
||||
be pointed to a non-default reference.
|
||||
|
||||
The output is written at the (OUT_FILE).
|
||||
|
||||
It is capable of identifying defines, functions, structs, typedefs,
|
||||
enums and enum symbols and create cross-references for all of them.
|
||||
It is also capable of distinguish #define used for specifying a Linux
|
||||
ioctl.
|
||||
|
||||
The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ .
|
||||
|
||||
The syntax for the ignore tag is:
|
||||
|
||||
|
||||
ignore \ **type**\ \ **name**\
|
||||
|
||||
The \ **ignore**\ means that it won't generate cross references for a
|
||||
\ **name**\ symbol of type \ **type**\ .
|
||||
|
||||
The syntax for the replace tag is:
|
||||
|
||||
|
||||
replace \ **type**\ \ **name**\ \ **new_value**\
|
||||
|
||||
The \ **replace**\ means that it will generate cross references for a
|
||||
\ **name**\ symbol of type \ **type**\ , but, instead of using the default
|
||||
replacement rule, it will use \ **new_value**\ .
|
||||
|
||||
For both statements, \ **type**\ can be either one of the following:
|
||||
|
||||
|
||||
\ **ioctl**\
|
||||
|
||||
The ignore or replace statement will apply to ioctl definitions like:
|
||||
|
||||
#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
|
||||
|
||||
|
||||
|
||||
\ **define**\
|
||||
|
||||
The ignore or replace statement will apply to any other #define found
|
||||
at C_FILE.
|
||||
|
||||
|
||||
|
||||
\ **typedef**\
|
||||
|
||||
The ignore or replace statement will apply to typedef statements at C_FILE.
|
||||
|
||||
|
||||
|
||||
\ **struct**\
|
||||
|
||||
The ignore or replace statement will apply to the name of struct statements
|
||||
at C_FILE.
|
||||
|
||||
|
||||
|
||||
\ **enum**\
|
||||
|
||||
The ignore or replace statement will apply to the name of enum statements
|
||||
at C_FILE.
|
||||
|
||||
|
||||
|
||||
\ **symbol**\
|
||||
|
||||
The ignore or replace statement will apply to the name of enum statements
|
||||
at C_FILE.
|
||||
|
||||
For replace statements, \ **new_value**\ will automatically use :c:type:
|
||||
references for \ **typedef**\ , \ **enum**\ and \ **struct**\ types. It will use :ref:
|
||||
for \ **ioctl**\ , \ **define**\ and \ **symbol**\ types. The type of reference can
|
||||
also be explicitly defined at the replace statement.
|
||||
|
||||
|
||||
|
||||
|
||||
********
|
||||
EXAMPLES
|
||||
********
|
||||
|
||||
|
||||
ignore define _VIDEODEV2_H
|
||||
|
||||
|
||||
Ignore a #define _VIDEODEV2_H at the C_FILE.
|
||||
|
||||
ignore symbol PRIVATE
|
||||
|
||||
|
||||
On a struct like:
|
||||
|
||||
enum foo { BAR1, BAR2, PRIVATE };
|
||||
|
||||
It won't generate cross-references for \ **PRIVATE**\ .
|
||||
|
||||
replace symbol BAR1 :c:type:\`foo\`
|
||||
replace symbol BAR2 :c:type:\`foo\`
|
||||
|
||||
|
||||
On a struct like:
|
||||
|
||||
enum foo { BAR1, BAR2, PRIVATE };
|
||||
|
||||
It will make the BAR1 and BAR2 enum symbols to cross reference the foo
|
||||
symbol at the C domain.
|
||||
|
||||
|
||||
****
|
||||
BUGS
|
||||
****
|
||||
|
||||
|
||||
Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
||||
|
||||
|
||||
*********
|
||||
COPYRIGHT
|
||||
*********
|
||||
|
||||
|
||||
Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
|
||||
|
||||
License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
|
||||
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,22 +1,22 @@
|
|||
#!/usr/bin/perl
|
||||
use strict;
|
||||
use Text::Tabs;
|
||||
use Getopt::Long;
|
||||
use Pod::Usage;
|
||||
|
||||
my $debug = 0;
|
||||
my $debug;
|
||||
my $help;
|
||||
my $man;
|
||||
|
||||
while ($ARGV[0] =~ m/^-(.*)/) {
|
||||
my $cmd = shift @ARGV;
|
||||
if ($cmd eq "--debug") {
|
||||
require Data::Dumper;
|
||||
$debug = 1;
|
||||
next;
|
||||
}
|
||||
die "argument $cmd unknown";
|
||||
}
|
||||
GetOptions(
|
||||
"debug" => \$debug,
|
||||
'help|?' => \$help,
|
||||
man => \$man
|
||||
) or pod2usage(2);
|
||||
|
||||
if (scalar @ARGV < 2 || scalar @ARGV > 3) {
|
||||
die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
|
||||
}
|
||||
pod2usage(1) if $help;
|
||||
pod2usage(-exitstatus => 0, -verbose => 2) if $man;
|
||||
pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3);
|
||||
|
||||
my ($file_in, $file_out, $file_exceptions) = @ARGV;
|
||||
|
||||
|
|
@ -28,6 +28,8 @@ my %enums;
|
|||
my %enum_symbols;
|
||||
my %structs;
|
||||
|
||||
require Data::Dumper if ($debug);
|
||||
|
||||
#
|
||||
# read the file and get identifiers
|
||||
#
|
||||
|
|
@ -330,3 +332,168 @@ print OUT "=" x length($title);
|
|||
print OUT "\n\n.. parsed-literal::\n\n";
|
||||
print OUT $data;
|
||||
close OUT;
|
||||
|
||||
__END__
|
||||
|
||||
=head1 NAME
|
||||
|
||||
parse_headers.pl - parse a C file, in order to identify functions, structs,
|
||||
enums and defines and create cross-references to a Sphinx book.
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
|
||||
|
||||
Where <options> can be: --debug, --help or --man.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 8
|
||||
|
||||
=item B<--debug>
|
||||
|
||||
Put the script in verbose mode, useful for debugging.
|
||||
|
||||
=item B<--help>
|
||||
|
||||
Prints a brief help message and exits.
|
||||
|
||||
=item B<--man>
|
||||
|
||||
Prints the manual page and exits.
|
||||
|
||||
=back
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Convert a C header or source file (C_FILE), into a ReStructured Text
|
||||
included via ..parsed-literal block with cross-references for the
|
||||
documentation files that describe the API. It accepts an optional
|
||||
EXCEPTIONS_FILE with describes what elements will be either ignored or
|
||||
be pointed to a non-default reference.
|
||||
|
||||
The output is written at the (OUT_FILE).
|
||||
|
||||
It is capable of identifying defines, functions, structs, typedefs,
|
||||
enums and enum symbols and create cross-references for all of them.
|
||||
It is also capable of distinguish #define used for specifying a Linux
|
||||
ioctl.
|
||||
|
||||
The EXCEPTIONS_FILE contain two types of statements: B<ignore> or B<replace>.
|
||||
|
||||
The syntax for the ignore tag is:
|
||||
|
||||
=over 8
|
||||
|
||||
ignore B<type> B<name>
|
||||
|
||||
=back
|
||||
|
||||
The B<ignore> means that it won't generate cross references for a
|
||||
B<name> symbol of type B<type>.
|
||||
|
||||
The syntax for the replace tag is:
|
||||
|
||||
=over 8
|
||||
|
||||
replace B<type> B<name> B<new_value>
|
||||
|
||||
=back
|
||||
|
||||
The B<replace> means that it will generate cross references for a
|
||||
B<name> symbol of type B<type>, but, instead of using the default
|
||||
replacement rule, it will use B<new_value>.
|
||||
|
||||
For both statements, B<type> can be either one of the following:
|
||||
|
||||
=over 8
|
||||
|
||||
=item B<ioctl>
|
||||
|
||||
The ignore or replace statement will apply to ioctl definitions like:
|
||||
|
||||
#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
|
||||
|
||||
=item B<define>
|
||||
|
||||
The ignore or replace statement will apply to any other #define found
|
||||
at C_FILE.
|
||||
|
||||
=item B<typedef>
|
||||
|
||||
The ignore or replace statement will apply to typedef statements at C_FILE.
|
||||
|
||||
=item B<struct>
|
||||
|
||||
The ignore or replace statement will apply to the name of struct statements
|
||||
at C_FILE.
|
||||
|
||||
=item B<enum>
|
||||
|
||||
The ignore or replace statement will apply to the name of enum statements
|
||||
at C_FILE.
|
||||
|
||||
=item B<symbol>
|
||||
|
||||
The ignore or replace statement will apply to the name of enum statements
|
||||
at C_FILE.
|
||||
|
||||
|
||||
For replace statements, B<new_value> will automatically use :c:type:
|
||||
references for B<typedef>, B<enum> and B<struct> types. It will use :ref:
|
||||
for B<ioctl>, B<define> and B<symbol> types. The type of reference can
|
||||
also be explicitly defined at the replace statement.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
ignore define _VIDEODEV2_H
|
||||
|
||||
=over 8
|
||||
|
||||
|
||||
Ignore a #define _VIDEODEV2_H at the C_FILE.
|
||||
|
||||
=back
|
||||
|
||||
ignore symbol PRIVATE
|
||||
|
||||
=over 8
|
||||
|
||||
On a struct like:
|
||||
|
||||
enum foo { BAR1, BAR2, PRIVATE };
|
||||
|
||||
It won't generate cross-references for B<PRIVATE>.
|
||||
|
||||
=back
|
||||
|
||||
replace symbol BAR1 :c:type:`foo`
|
||||
replace symbol BAR2 :c:type:`foo`
|
||||
|
||||
=over 8
|
||||
|
||||
On a struct like:
|
||||
|
||||
enum foo { BAR1, BAR2, PRIVATE };
|
||||
|
||||
It will make the BAR1 and BAR2 enum symbols to cross reference the foo
|
||||
symbol at the C domain.
|
||||
|
||||
=back
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Report bugs to Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>.
|
||||
|
||||
License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
|
||||
|
||||
This is free software: you are free to change and redistribute it.
|
||||
There is NO WARRANTY, to the extent permitted by law.
|
||||
|
||||
=cut
|
||||
|
|
|
|||
|
|
@ -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