docs: kdoc: move kernel-doc to tools/docs
kernel-doc is the last documentation-related tool still living outside of the tools/docs directory; the time has come to move it over. [mchehab: fixed kdoc lib location] Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org>master
Jonathan Corbet
parent
24f984aa11
commit
eba6ffd126
|
|
@ -585,7 +585,7 @@ pdf_documents = [
|
|||
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
|
||||
# the Docs). In a normal build, these are supplied from the Makefile via command
|
||||
# line arguments.
|
||||
kerneldoc_bin = "../scripts/kernel-doc.py"
|
||||
kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now
|
||||
kerneldoc_srctree = ".."
|
||||
|
||||
def setup(app):
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual
|
|||
output generation may be used to verify proper formatting of the
|
||||
documentation comments. For example::
|
||||
|
||||
scripts/kernel-doc -v -none drivers/foo/bar.c
|
||||
tools/docs/kernel-doc -v -none drivers/foo/bar.c
|
||||
|
||||
The documentation format of ``.c`` files is also verified by the kernel build
|
||||
when it is requested to perform extra gcc checks::
|
||||
|
|
@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a
|
|||
left parenthesis ('(') for function-like macros or not followed by one
|
||||
for object-like macros.
|
||||
|
||||
Function-like macros are handled like functions by ``scripts/kernel-doc``.
|
||||
Function-like macros are handled like functions by ``tools/docs/kernel-doc``.
|
||||
They may have a parameter list. Object-like macros have do not have a
|
||||
parameter list.
|
||||
|
||||
|
|
@ -596,8 +596,8 @@ from the source file.
|
|||
|
||||
The kernel-doc extension is included in the kernel source tree, at
|
||||
``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
|
||||
``scripts/kernel-doc`` script to extract the documentation comments from the
|
||||
source.
|
||||
``tools/docs/kernel-doc`` script to extract the documentation comments from
|
||||
the source.
|
||||
|
||||
.. _kernel_doc:
|
||||
|
||||
|
|
|
|||
|
|
@ -180,7 +180,7 @@ architecture.
|
|||
KDOCFLAGS
|
||||
---------
|
||||
Specify extra (warning/error) flags for kernel-doc checks during the build,
|
||||
see scripts/kernel-doc for which flags are supported. Note that this doesn't
|
||||
see tools/docs/kernel-doc for which flags are supported. Note that this doesn't
|
||||
(currently) apply to documentation builds.
|
||||
|
||||
ARCH
|
||||
|
|
|
|||
|
|
@ -614,7 +614,7 @@ it.
|
|||
|
||||
When commenting the kernel API functions, please use the kernel-doc format.
|
||||
See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
|
||||
``scripts/kernel-doc`` for details. Note that the danger of over-commenting
|
||||
``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting
|
||||
applies to kernel-doc comments all the same. Do not add boilerplate
|
||||
kernel-doc which simply reiterates what's obvious from the signature
|
||||
of the function.
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati correttamente, potete
|
|||
eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza
|
||||
che questo produca alcuna documentazione. Per esempio::
|
||||
|
||||
scripts/kernel-doc -v -none drivers/foo/bar.c
|
||||
tools/docs/kernel-doc -v -none drivers/foo/bar.c
|
||||
|
||||
Il formato della documentazione è verificato della procedura di generazione
|
||||
del kernel quando viene richiesto di effettuare dei controlli extra con GCC::
|
||||
|
|
@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro simile a funzione sia
|
|||
immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a
|
||||
oggetti no.
|
||||
|
||||
Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``.
|
||||
Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kernel-doc``.
|
||||
Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un
|
||||
elenco di parametri.
|
||||
|
||||
|
|
@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*).
|
|||
|
||||
L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare
|
||||
in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato
|
||||
lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione
|
||||
lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazione
|
||||
dai file sorgenti.
|
||||
|
||||
Come utilizzare kernel-doc per generare pagine man
|
||||
|
|
@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man
|
|||
Se volete utilizzare kernel-doc solo per generare delle pagine man, potete
|
||||
farlo direttamente dai sorgenti del kernel::
|
||||
|
||||
$ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
|
||||
$ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
|
||||
|
|
|
|||
|
|
@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto.
|
|||
|
||||
Al comentar las funciones de la API del kernel, utilice el formato
|
||||
kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ <doc_guide>`
|
||||
y ``scripts/kernel-doc`` para más detalles.
|
||||
y ``tools/docs/kernel-doc`` para más detalles.
|
||||
|
||||
El estilo preferido para comentarios largos (de varias líneas) es:
|
||||
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取
|
|||
用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式
|
||||
是否正确。例如::
|
||||
|
||||
scripts/kernel-doc -v -none drivers/foo/bar.c
|
||||
tools/docs/kernel-doc -v -none drivers/foo/bar.c
|
||||
|
||||
当请求执行额外的gcc检查时，内核构建将验证文档格式::
|
||||
|
||||
|
|
@ -473,7 +473,7 @@ doc: *title*
|
|||
如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。
|
||||
|
||||
kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。
|
||||
在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。
|
||||
在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。
|
||||
|
||||
.. _kernel_doc_zh:
|
||||
|
||||
|
|
@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k
|
|||
|
||||
如果您只想使用kernel-doc生成手册页，可以从内核git树这样做::
|
||||
|
||||
$ scripts/kernel-doc -man \
|
||||
$ tools/docs/kernel-doc -man \
|
||||
$(git grep -l '/\*\*' -- :^Documentation :^tools) \
|
||||
| scripts/split-man.pl /tmp/man
|
||||
|
||||
一些旧版本的git不支持路径排除语法的某些变体。
|
||||
以下命令之一可能适用于这些版本::
|
||||
|
||||
$ scripts/kernel-doc -man \
|
||||
$ tools/docs/kernel-doc -man \
|
||||
$(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
|
||||
| scripts/split-man.pl /tmp/man
|
||||
|
||||
$ scripts/kernel-doc -man \
|
||||
$ tools/docs/kernel-doc -man \
|
||||
$(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
|
||||
| scripts/split-man.pl /tmp/man
|
||||
|
||||
|
|
|
|||
|
|
@ -174,7 +174,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确
|
|||
KDOCFLAGS
|
||||
---------
|
||||
指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看
|
||||
scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
|
||||
tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。
|
||||
|
||||
ARCH
|
||||
----
|
||||
|
|
|
|||
|
|
@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供
|
|||
也可以加上它做这些事情的原因。
|
||||
|
||||
当注释内核 API 函数时，请使用 kernel-doc 格式。详见
|
||||
Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
|
||||
Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
|
||||
|
||||
长 (多行) 注释的首选风格是：
|
||||
|
||||
|
|
|
|||
|
|
@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供
|
|||
也可以加上它做這些事情的原因。
|
||||
|
||||
當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見
|
||||
Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。
|
||||
Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。
|
||||
|
||||
長 (多行) 註釋的首選風格是：
|
||||
|
||||
|
|
|
|||
|
|
@ -7523,7 +7523,6 @@ S: Maintained
|
|||
P: Documentation/doc-guide/maintainer-profile.rst
|
||||
T: git git://git.lwn.net/linux.git docs-next
|
||||
F: Documentation/
|
||||
F: scripts/kernel-doc*
|
||||
F: tools/lib/python/*
|
||||
F: tools/docs/
|
||||
F: tools/net/ynl/pyynl/lib/doc_generator.py
|
||||
|
|
@ -7561,7 +7560,6 @@ M: Mauro Carvalho Chehab <mchehab@kernel.org>
|
|||
L: linux-doc@vger.kernel.org
|
||||
S: Maintained
|
||||
F: Documentation/sphinx/
|
||||
F: scripts/kernel-doc*
|
||||
F: tools/lib/python/*
|
||||
F: tools/docs/
|
||||
|
||||
|
|
|
|||
2
Makefile
2
Makefile
|
|
@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config
|
|||
|
||||
# the KERNELDOC macro needs to be exported, as scripts/Makefile.build
|
||||
# has a logic to call it
|
||||
KERNELDOC = $(srctree)/scripts/kernel-doc.py
|
||||
KERNELDOC = $(srctree)/tools/docs/kernel-doc
|
||||
export KERNELDOC
|
||||
|
||||
KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
|
||||
|
|
|
|||
|
|
@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \
|
|||
|
||||
quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@)
|
||||
cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \
|
||||
$(srctree)/scripts/kernel-doc -none -Werror $<; touch $@
|
||||
$(KERNELDOC) -none -Werror $<; touch $@
|
||||
|
||||
$(obj)/%.hdrtest: $(src)/%.h FORCE
|
||||
$(call if_changed_dep,hdrtest)
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
kernel-doc.py
|
||||
|
|
@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do
|
|||
if [[ ${FILES_INCLUDED[$file]+_} ]]; then
|
||||
continue;
|
||||
fi
|
||||
str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null)
|
||||
str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null)
|
||||
if [[ -n "$str" ]]; then
|
||||
echo "$file"
|
||||
fi
|
||||
|
|
|
|||
|
|
@ -108,7 +108,7 @@ import sys
|
|||
|
||||
# Import Python modules
|
||||
|
||||
LIB_DIR = "../tools/lib/python"
|
||||
LIB_DIR = "../lib/python"
|
||||
SRC_DIR = os.path.dirname(os.path.realpath(__file__))
|
||||
|
||||
sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR))
|
||||
|
|
@ -246,7 +246,7 @@ class SphinxBuilder:
|
|||
#
|
||||
self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build")
|
||||
self.kerneldoc = self.get_path(os.environ.get("KERNELDOC",
|
||||
"scripts/kernel-doc.py"))
|
||||
"tools/docs/kernel-doc"))
|
||||
self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True)
|
||||
|
||||
#
|
||||
|
|
|
|||
Loading…
Reference in New Issue