diff options
Diffstat (limited to 'Documentation/doc-guide')
| -rw-r--r-- | Documentation/doc-guide/checktransupdate.rst | 6 | ||||
| -rw-r--r-- | Documentation/doc-guide/contributing.rst | 2 | ||||
| -rw-r--r-- | Documentation/doc-guide/kernel-doc.rst | 33 | ||||
| -rw-r--r-- | Documentation/doc-guide/parse-headers.rst | 189 | ||||
| -rw-r--r-- | Documentation/doc-guide/sphinx.rst | 6 |
5 files changed, 119 insertions, 117 deletions
diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst index dfaf9d373747..7b25375cc6d9 100644 --- a/Documentation/doc-guide/checktransupdate.rst +++ b/Documentation/doc-guide/checktransupdate.rst @@ -27,15 +27,15 @@ Usage :: - ./scripts/checktransupdate.py --help + tools/docs/checktransupdate.py --help Please refer to the output of argument parser for usage details. Samples -- ``./scripts/checktransupdate.py -l zh_CN`` +- ``tools/docs/checktransupdate.py -l zh_CN`` This will print all the files that need to be updated in the zh_CN locale. -- ``./scripts/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst`` +- ``tools/docs/checktransupdate.py Documentation/translations/zh_CN/dev-tools/testing-overview.rst`` This will only print the status of the specified file. Then the output is something like: diff --git a/Documentation/doc-guide/contributing.rst b/Documentation/doc-guide/contributing.rst index 662c7a840cd5..f8047e633113 100644 --- a/Documentation/doc-guide/contributing.rst +++ b/Documentation/doc-guide/contributing.rst @@ -152,7 +152,7 @@ generate links to that documentation. Adding ``kernel-doc`` directives to the documentation to bring those comments in can help the community derive the full value of the work that has gone into creating them. -The ``scripts/find-unused-docs.sh`` tool can be used to find these +The ``tools/docs/find-unused-docs.sh`` tool can be used to find these overlooked comments. Note that the most value comes from pulling in the documentation for diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index af9697e60165..fd89a6d56ea9 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -405,6 +405,10 @@ Domain`_ references. ``%CONST`` Name of a constant. (No cross-referencing, just formatting.) + Examples:: + + %0 %NULL %-1 %-EFAULT %-EINVAL %-ENOMEM + ````literal```` A literal block that should be handled as-is. The output will use a ``monospaced font``. @@ -579,20 +583,23 @@ source. How to use kernel-doc to generate man pages ------------------------------------------- -If you just want to use kernel-doc to generate man pages you can do this -from the kernel git tree:: +To generate man pages for all files that contain kernel-doc markups, run:: + + $ make mandocs - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- :^Documentation :^tools) \ - | scripts/split-man.pl /tmp/man +Or calling ``script-build-wrapper`` directly:: -Some older versions of git do not support some of the variants of syntax for -path exclusion. One of the following commands may work for those versions:: + $ ./tools/docs/sphinx-build-wrapper mandocs - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ - | scripts/split-man.pl /tmp/man +The output will be at ``/man`` directory inside the output directory +(by default: ``Documentation/output``). + +Optionally, it is possible to generate a partial set of man pages by +using SPHINXDIRS: + + $ make SPHINXDIRS=driver-api/media mandocs + +.. note:: - $ scripts/kernel-doc -man \ - $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ - | scripts/split-man.pl /tmp/man + When SPHINXDIRS={subdir} is used, it will only generate man pages for + the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file. diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst index 204b025f1349..a7bb01ff04eb 100644 --- a/Documentation/doc-guide/parse-headers.rst +++ b/Documentation/doc-guide/parse-headers.rst @@ -5,173 +5,168 @@ 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 +userspace API files has an additional advantage: 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 +The :ref:`parse_headers.py <parse_headers>` provides a way to generate such cross-references. It has to be called via Makefile, while building the documentation. Please see ``Documentation/userspace-api/media/Makefile`` for an example about how to use it inside the Kernel tree. .. _parse_headers: -parse_headers.pl -^^^^^^^^^^^^^^^^ +tools/docs/parse_headers.py +^^^^^^^^^^^^^^^^^^^^^^^^^^^ NAME **** - -parse_headers.pl - parse a C file, in order to identify functions, structs, +parse_headers.py - parse a C file, in order to identify functions, structs, enums and defines and create cross-references to a Sphinx book. +USAGE +***** + +parse-headers.py [-h] [-d] [-t] ``FILE_IN`` ``FILE_OUT`` ``FILE_RULES`` SYNOPSIS ******** - -\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] - -Where <options> can be: --debug, --help or --usage. - - -OPTIONS -******* - - - -\ **--debug**\ - - Put the script in verbose mode, useful for debugging. - - - -\ **--usage**\ - - Prints a brief help message and exits. - - - -\ **--help**\ - - Prints a more detailed help message and exits. - - -DESCRIPTION -*********** - - -Convert a C header or source file (C_FILE), into a reStructuredText +Converts a C header or source file ``FILE_IN`` 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). +``FILE_RULES`` file to describe what elements will be either ignored or +be pointed to a non-default reference type/name. -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 output is written at ``FILE_OUT``. -The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\ or \ **replace**\ . +It is capable of identifying ``define``, ``struct``, ``typedef``, ``enum`` +and enum ``symbol``, creating cross-references for all of them. -The syntax for the ignore tag is: +It is also capable of distinguishing ``#define`` used for specifying +Linux-specific macros used to define ``ioctl``. +The optional ``FILE_RULES`` contains a set of rules like:: -ignore \ **type**\ \ **name**\ + ignore ioctl VIDIOC_ENUM_FMT + replace ioctl VIDIOC_DQBUF vidioc_qbuf + replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ :c:type:`v4l2_event_motion_det` -The \ **ignore**\ means that it won't generate cross references for a -\ **name**\ symbol of type \ **type**\ . +POSITIONAL ARGUMENTS +******************** -The syntax for the replace tag is: + ``FILE_IN`` + Input C file + ``FILE_OUT`` + Output RST file -replace \ **type**\ \ **name**\ \ **new_value**\ + ``FILE_RULES`` + Exceptions file (optional) -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: +OPTIONS +******* + ``-h``, ``--help`` + show a help message and exit + ``-d``, ``--debug`` + Increase debug level. Can be used multiple times + ``-t``, ``--toc`` + instead of a literal block, outputs a TOC table at the RST file -\ **ioctl**\ - The ignore or replace statement will apply to ioctl definitions like: +DESCRIPTION +*********** - #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) +Creates an enriched version of a Kernel header file with cross-links +to each C data structure type, from ``FILE_IN``, formatting it with +reStructuredText notation, either as-is or as a table of contents. +It accepts an optional ``FILE_RULES`` which describes what elements will be +either ignored or be pointed to a non-default reference, and optionally +defines the C namespace to be used. +It is meant to allow having more comprehensive documentation, where +uAPI headers will create cross-reference links to the code. -\ **define**\ +The output is written at the ``FILE_OUT``. - The ignore or replace statement will apply to any other #define found - at C_FILE. +The ``FILE_RULES`` may contain contain three types of statements: +**ignore**, **replace** and **namespace**. +By default, it create rules for all symbols and defines, but it also +allows parsing an exception file. Such file contains a set of rules +using the syntax below: +1. Ignore rules: -\ **typedef**\ + ignore *type* *symbol* - The ignore or replace statement will apply to typedef statements at C_FILE. +Removes the symbol from reference generation. +2. Replace rules: + replace *type* *old_symbol* *new_reference* -\ **struct**\ + Replaces *old_symbol* with a *new_reference*. + The *new_reference* can be: - The ignore or replace statement will apply to the name of struct statements - at C_FILE. + - A simple symbol name; + - A full Sphinx reference. +3. Namespace rules + namespace *namespace* -\ **enum**\ + Sets C *namespace* to be used during cross-reference generation. Can + be overridden by replace rules. - The ignore or replace statement will apply to the name of enum statements - at C_FILE. +On ignore and replace rules, *type* can be: + - ioctl: + for defines of the form ``_IO*``, e.g., ioctl definitions + - define: + for other defines -\ **symbol**\ + - symbol: + for symbols defined within enums; - The ignore or replace statement will apply to the name of enum value - at C_FILE. + - typedef: + for typedefs; - 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. + - enum: + for the name of a non-anonymous enum; + - struct: + for structs. EXAMPLES ******** +- Ignore a define ``_VIDEODEV2_H`` at ``FILE_IN``:: -ignore define _VIDEODEV2_H - - -Ignore a #define _VIDEODEV2_H at the C_FILE. - -ignore symbol PRIVATE - + ignore define _VIDEODEV2_H -On a struct like: +- On an data structure like this enum:: -enum foo { BAR1, BAR2, PRIVATE }; + enum foo { BAR1, BAR2, PRIVATE }; -It won't generate cross-references for \ **PRIVATE**\ . + It won't generate cross-references for ``PRIVATE``:: -replace symbol BAR1 :c:type:\`foo\` -replace symbol BAR2 :c:type:\`foo\` + ignore symbol PRIVATE + At the same struct, instead of creating one cross reference per symbol, + make them all point to the ``enum foo`` C type:: -On a struct like: + replace symbol BAR1 :c:type:\`foo\` + replace symbol BAR2 :c:type:\`foo\` -enum foo { BAR1, BAR2, PRIVATE }; -It will make the BAR1 and BAR2 enum symbols to cross reference the foo -symbol at the C domain. +- Use C namespace ``MC`` for all symbols at ``FILE_IN``:: + namespace MC BUGS **** @@ -184,7 +179,7 @@ COPYRIGHT ********* -Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>. +Copyright (c) 2016, 2025 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>. License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>. diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 607589592bfb..51c370260f3b 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -106,7 +106,7 @@ There's a script that automatically checks for Sphinx dependencies. If it can recognize your distribution, it will also give a hint about the install command line options for your distro:: - $ ./scripts/sphinx-pre-install + $ ./tools/docs/sphinx-pre-install Checking if the needed tools for Fedora release 26 (Twenty Six) are available Warning: better to also install "texlive-luatex85". You should run: @@ -116,7 +116,7 @@ command line options for your distro:: . sphinx_2.4.4/bin/activate pip install -r Documentation/sphinx/requirements.txt - Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + Can't build as 1 mandatory dependency is missing at ./tools/docs/sphinx-pre-install line 468. By default, it checks all the requirements for both html and PDF, including the requirements for images, math expressions and LaTeX build, and assumes @@ -149,7 +149,7 @@ a venv with it with, and install minimal requirements with:: A more comprehensive test can be done by using: - scripts/test_doc_build.py + tools/docs/test_doc_build.py Such script create one Python venv per supported version, optionally building documentation for a range of Sphinx versions. |