.. -*- coding: utf-8; mode: rst -*- .. include:: refs.txt .. _conf.py: http://www.sphinx-doc.org/en/stable/config.html .. _kernel-doc-directive: ============================ kernel-doc in reST documents ============================ To integrate :ref:`kernel-doc ` comments into a reST document (e.g. in a *book*), there exists a reST-directive_ named ``kernel-doc`` . The directive comes with options to fine grain control which parts should be placed into the reST document. With no options given, the complete kernel-doc comments from a source file will be inserted. So, the first and very simple example is: .. code-block:: rst My Lib ====== .. kernel-doc:: ../src/mylib.h With this small example (a file ``doc/mylib.rst``) the kernel-doc comments from the ``src/mylib.h`` will be inserted direct under the chapter "My Lib". The "DOC:" sections, the function and the type descriptions will be inserted in the order they appear in the source file. Mostly you want to select more fine grained, read on to see how. .. contents:: Contents :depth: 2 :local: :backlinks: entry .. _kernel-doc-options: kernel-doc options ================== Here is a short overview of the directives options: .. code-block:: rst .. kernel-doc:: :doc:
:no-header: :export: :internal: :exp-method: :exp-ids: :symbols: :module: :man-sect: :snippets: :language: :linenos: :debug: The argument ```` is required and points to the source file. The pathname is relative to the pathname of the ``kernel-doc`` directive. Absolute pathnames are relative to ``srctree``, which can be set in the environment or using :ref:`kernel_doc_srctree ` in the sphinx conf.py_ (if unset, defaults to CWD). The options have the following meaning, but be aware that not all combinations of these options make sense: ``:doc:
`` (:ref:`doc_sections`) Include content of the ``DOC:`` section titled ``
``. Spaces are allowed in ``
``; do not quote the ``
``. The next option make only sense in conjunction with option ``doc``: ``:no-header:`` (:ref:`opt_no-header`) Do not output DOC: section's title. Useful, if the surrounding context already has a heading, and the DOC: section title is only used as an identifier. Take in mind, that this option will not suppress any native reST heading markup in the comment. ``:export: [ [, ...]]`` (:ref:`opt_export`) Include documentation of all function, struct or whatever definitions in ```` and exported using one of the :ref:`export symbols ` (:ref:`macro `) either in ```` or in any of the files specified by ````. The ```` (glob) is useful when the kernel-doc comments have been placed in header files, while *EXPORT_SYMBOL* are next to the function definitions. ``:internal: [ [, ...]]`` (:ref:`opt_internal`) Include documentation of all documented definitions, **not** exported by one of the :ref:`export symbols ` (:ref:`macro `) either in ```` or in any of the files specified by ````. .. _exp-method option: ``:exp-method: `` Change the way exported symbols are specified in source code. Default value ``macro`` if not provided, can be set globally by :ref:`kernel_doc_exp_method ` in the sphinx conf.py_. The ```` must one of the following value: ``macro`` Exported symbols are specified by macros (whose names are controlled by ``exp-ids`` option) invoked in the source the following way: ``THIS_IS_AN_EXPORTED_SYMBOL(symbol)`` ``attribute`` Exported symbols are specified definition using a specific attribute (controlled by ``exp-ids`` option) either in their declaration or definition: ``THIS_IS_AN_EXPORTED_SYMBOL int symbol(void* some_arg) {...}`` .. _exp-ids option: ``:exp-ids: `` Use the specified list of identifiers instead of default value: ``EXPORT_SYMBOL``, ``EXPORT_SYMBOL_GPL`` & ``EXPORT_SYMBOL_GPL_FUTURE``. Default value can be overriden globally by sphinx conf.py_ option :ref:`kernel_doc_exp_ids `. ``:known-attrs: `` Specified a list of function attributes that are known and must be hidden when displaying function prototype. When ``:exp-method:`` is set to ``attribute`` the list in ``:exp-ids:`` is considered as known and added implicitly to this list of known attributes. The default list is empty and can be adjusted by the sphinx configuration option :ref:`kernel_doc_known_attrs `. ``:symbols: `` (:ref:`kernel-doc-functions`, :ref:`kernel-doc-structs`) Include documentation for each named definition. For backward compatibility there exists an alias ``functions``. ``:module: `` The option ``:module: `` sets a module-name and is used in ``.. c:namespace-push:`` `[ref] `__. The module-name (aka *namespace*) is used as a prefix in the cross links. For a detailed example have a look at section :ref:`kernel-doc-functions`. ``:man-sect: `` Section number of the manual pages (see "``$ man man-pages``""). Optional set :ref:`kernel_doc_mansect ` option in sphinx conf.py_. The man-pages are build by the ``kernel-doc-man`` builder. Read on here: :ref:`man-pages` ``:snippets: `` Inserts the source-code passage(s) marked with the snippet ``name``. The snippet is inserted with a `code-block:: `_ directive. The next options make only sense in conjunction with option ``snippets``: ``language `` Set highlighting language of the snippet code-block. ``linenos`` Set line numbers in the snippet code-block. ``:debug:`` Inserts a code-block with the generated reST source. This might sometimes helpful to see how the kernel-doc parser transforms the kernel-doc markup to reST markup. .. _kernel-doc-functions: Insert function's documentation =============================== In :ref:`all-in-a-tumble.c-src` there is the following function definition which is documented by a :ref:`kernel-doc-syntax`. .. kernel-doc:: ./all-in-a-tumble.c :snippets: user_function :language: c To include the documentation from C-:ref:`kernel-doc-syntax-functions` into your reStructuredText document use the following markup: .. code-block:: rst .. kernel-doc:: ./all-in-a-tumble.c :symbols: user_function :module: foo This will convert the :ref:`kernel-doc-syntax` into the following reST markup: .. kernel-doc:: ./all-in-a-tumble.c :symbols: user_function :module: foo :debug: ---- In the next view lines you will see how the documentation will be rendered: .. admonition:: kernel-doc option ``:symbols:`` :class: rst-example .. kernel-doc:: ./all-in-a-tumble.c :symbols: user_function :module: foo In reST documents you can cross reference to the function or directly to one of the sections of this documentation: .. code-block:: rst * C constructs in Sphinx >= 3.1 :c:func:`foo.user_function` * refer sections: :ref:`Example `, :ref:`Return ` ... .. admonition:: cross referencing function's documentation :class: rst-example * C constructs in Sphinx >= 3.1 :c:func:`foo.user_function` * refer sections: :ref:`Example `, :ref:`Return ` ... .. _kernel-doc-structs: .. _kernel-doc-unions: .. _kernel-doc-enums: .. _kernel-doc-typedefs: structs, unions, enums and typedefs =================================== The following example inserts the documentation of struct ``my_long_struct``. .. code-block:: rst .. kernel-doc:: ./all-in-a-tumble.h :symbols: my_long_struct :module: example Here in this documentation the examples from the :ref:`all-in-a-tumble-src` are located in the ``example`` module (aka *namespace*). To `Cross-referencing C constructs`_ within this module you can use the Sphinx *namespace* or to point to a section you can use the anchors inserted by the ``.. kernel-doc::`` directive. .. code-block:: rst * C constructs in Sphinx >= 3.1 :c:struct:`example.my_long_struct` * refer sections: :ref:`Definition `, :ref:`Members ` ... .. admonition:: option ``:symbols: structs, unions, enums and typedefs`` :class: rst-example * C constructs in Sphinx >= 3.1 :c:struct:`example.my_long_struct` * refer sections: :ref:`Definition `, :ref:`Members ` ... .. _kernel-doc-snippets: Snippets ======== The kernel-doc Parser supports a markup for :ref:`kernel-doc-syntax-snippets`. By example; In the the :ref:`all-in-a-tumble examples ` we have a small source code example: .. code-block:: c /* parse-SNIP: hello-world */ #include int main() { printf("Hello World\n"); return 0; } /* parse-SNAP: */ To insert the code passage between SNIP & SNAP use: .. code-block:: rst .. kernel-doc:: ./all-in-a-tumble.c :snippets: hello-world :language: c :linenos: And here is the rendered example: .. kernel-doc:: ./all-in-a-tumble.c :snippets: hello-world :language: c :linenos: .. _kernel-doc-man-sect: man pages (:man-sect:) ====================== To get man pages from kernel-doc comments, add the ``:man-sect:`` option to your kernel-doc directives. E.g. to get man-pages of media's remote control (file ``media/kapi/rc-core.rst``) add ``:man-sect: 9`` to all the kernel-doc includes. .. code-block:: rst Remote Controller devices ========================= Remote Controller core ---------------------- .. kernel-doc:: include/media/rc-core.h :man-sect: 9 .. kernel-doc:: include/media/rc-map.h :man-sect: 9 LIRC ---- .. kernel-doc:: include/media/lirc_dev.h :man-sect: 9 If you don't want to edit all your kernel-doc directives to get man page from, set a global man-sect in your ``conf.py``, see sphinx configuration :ref:`kernel_doc_mansect ` and about build look at: :ref:`man-pages` Highlights and cross-references =============================== The following special patterns are recognized in the kernel-doc comment descriptive text and converted to proper reStructuredText markup and `Sphinx's C Domain`_ references. .. attention:: The below are **only** recognized within kernel-doc comments, **not** within normal reStructuredText documents. ``funcname()`` Function reference. ``@parameter`` Name of a function parameter. (No cross-referencing, just formatting.) ``%CONST`` Name of a constant. (No cross-referencing, just formatting.) ````literal```` A literal block that should be handled as-is. The output will use a ``monospaced font``. Useful if you need to use special characters that would otherwise have some meaning either by kernel-doc script of by reStructuredText. This is particularly useful if you need to use things like ``%ph`` inside a function description. ``$ENVVAR`` Name of an environment variable. (No cross-referencing, just formatting.) ``&struct name`` Structure reference. ``&enum name`` Enum reference. ``&typedef name`` Typedef reference. ``&struct_name->member`` or ``&struct_name.member`` Structure or union member reference. The cross-reference will be to the struct or union definition, not the member directly. ``&name`` A generic type reference. Prefer using the full reference described above instead. This is mostly for legacy comments. .. _kernel-doc-config: kernel-doc config ================= Within the `sphinx config`_ file (``conf.py`` or ``my_project.conf``) you can set the following option. .. _kernel_doc_exp_method: kernel_doc_exp_method: :py:obj:`linuxdoc.kernel_doc.DEFAULT_EXP_METHOD` Set parser's default value for kernel-doc directive option ``:exp-method:`` (details see: :ref:`exp-method `) .. _kernel_doc_exp_ids: kernel_doc_exp_ids: :py:obj:`linuxdoc.kernel_doc.DEFAULT_EXP_IDS` Set parser's default value for kernel-doc directive option ``:exp-ids:``. (details see: :ref:`exp-ids `) kernel_doc_known_attrs: ``[...]`` Set parser's default value for kernel-doc directive option ``:known-attrs:`` (details see: :ref:`kernel-doc-options`) kernel_doc_mansect: ``None`` Global fallback for man section of kernel-doc directives. Set this value if you want to create man pages for those kernel-doc directives, which has not been set a ``:man-sect:`` value. The default is ``None``, which means; do the opposite and create only man pages for those directives which has been set the ``:man-sect:`` option (``None`` is what you mostly want). kernel_doc_mode: ``reST`` Set parser's default kernel-doc mode ``[reST|kernel-doc]``. Normally you wont set anything other than the default! See :ref:`reST-kernel-doc-mode` and :ref:`vintage-kernel-doc-mode`. kernel_doc_verbose_warn: ``True`` If true, more warnings will be logged. E.g. a missing description of a function's return value will be logged. kernel_doc_raise_error: ``True`` If ``True`` fatal errors (like missing function descriptions) raise an error. The default is ``True``. This means that the build process break every time a serve error in the documentation build occur. Often it might be better the build continues and inserts Oops on serve errors. For this, set ``kernel_doc_raise_error`` to ``False``. In the next example, the documentation of a non existing definition name ``no_longer_exists`` is required: .. code-block:: rst .. kernel-doc:: ./all-in-a-tumble.h :symbols: no_longer_exist Since this definition not exists (anymore), the following TODO entry with Oops is inserted (again; only when ``kernel_doc_raise_error`` is ``False``). .. admonition:: parser error inserts a ".. todo::" directive with *Oops* in :class: rst-example .. kernel-doc:: ./all-in-a-tumble.h :symbols: no_longer_exist kernel_doc_srctree: ``None`` Set the pathname used as a base for absolute pathnames in kernel-doc directive. It can be overridden by the ``srctree`` environment variable.