diff options
| -rw-r--r-- | Documentation/00-INDEX | 2 | ||||
| -rw-r--r-- | Documentation/conf.py | 2 | ||||
| -rw-r--r-- | Documentation/doc-guide/conf.py | 10 | ||||
| -rw-r--r-- | Documentation/doc-guide/docbook.rst | 90 | ||||
| -rw-r--r-- | Documentation/doc-guide/index.rst | 20 | ||||
| -rw-r--r-- | Documentation/doc-guide/kernel-doc.rst (renamed from Documentation/kernel-documentation.rst) | 316 | ||||
| -rw-r--r-- | Documentation/doc-guide/parse-headers.rst | 208 | ||||
| -rw-r--r-- | Documentation/doc-guide/sphinx.rst | 219 | ||||
| -rw-r--r-- | Documentation/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/kernel-doc-nano-HOWTO.txt | 2 | ||||
| -rw-r--r-- | Documentation/process/4.Coding.rst | 4 | ||||
| -rw-r--r-- | Documentation/process/coding-style.rst | 4 | ||||
| -rwxr-xr-x | Documentation/sphinx/parse-headers.pl | 193 | ||||
| -rw-r--r-- | Documentation/translations/zh_CN/CodingStyle | 2 |
14 files changed, 737 insertions, 337 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index e2e74448d425..c08de5574d48 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -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. diff --git a/Documentation/conf.py b/Documentation/conf.py index ba38bcf485a9..1ac958c0333d 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -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', diff --git a/Documentation/doc-guide/conf.py b/Documentation/doc-guide/conf.py new file mode 100644 index 000000000000..fd3731182d5a --- /dev/null +++ b/Documentation/doc-guide/conf.py @@ -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'), +] diff --git a/Documentation/doc-guide/docbook.rst b/Documentation/doc-guide/docbook.rst new file mode 100644 index 000000000000..d8bf04308b43 --- /dev/null +++ b/Documentation/doc-guide/docbook.rst @@ -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. diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst new file mode 100644 index 000000000000..6fff4024606e --- /dev/null +++ b/Documentation/doc-guide/index.rst @@ -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` diff --git a/Documentation/kernel-documentation.rst b/Documentation/doc-guide/kernel-doc.rst index 3fcf0ad6e5f0..b32e4813ff6f 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -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. diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst new file mode 100644 index 000000000000..615e25ec64bb --- /dev/null +++ b/Documentation/doc-guide/parse-headers.rst @@ -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. diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst new file mode 100644 index 000000000000..96fe7ccb2c67 --- /dev/null +++ b/Documentation/doc-guide/sphinx.rst @@ -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 diff --git a/Documentation/index.rst b/Documentation/index.rst index 286d92bad208..bf3eb3ad6ad5 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -38,7 +38,7 @@ merged much easier. process/index dev-tools/index - kernel-documentation + doc-guide/index Kernel API documentation ------------------------ diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 062e3af271b7..104740ea0041 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -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 ===================== diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 983d628c1112..2a728d898fc5 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -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, diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 3e7905172000..d20d52a4d812 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -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: diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl index db0186a7618f..20dbdf55c71e 100755 --- a/Documentation/sphinx/parse-headers.pl +++ b/Documentation/sphinx/parse-headers.pl @@ -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 diff --git a/Documentation/translations/zh_CN/CodingStyle b/Documentation/translations/zh_CN/CodingStyle index b02738042799..dc101f48e713 100644 --- a/Documentation/translations/zh_CN/CodingStyle +++ b/Documentation/translations/zh_CN/CodingStyle @@ -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 风格 “// ...” 注释。 |