DOCS.ECLASS

章节: eclass-manpages (5)
更新时间: 2024年11月
索引返回主目录

名称

docs.eclass - 用于构建文档的简单 eclass。

描述

一个简单的 eclass，提供构建文档的基本功能和变量。

请注意，此 eclass 会无条件地追加到 RDEPEND 和 DEPEND 中。

此 eclass 还将“doc”追加到 IUSE 中，并将 HTML_DOCS 自动设置为编译后文档的位置，然后 'einstalldocs' 将自动将文档安装到正确的目录。

此 eclass 的目的是简化添加其他文档构建器的过程。为此，请为您的文档构建器添加 <DOCS_BUILDER>_deps 和 <DOCS_BUILDER>_compile 函数。对于基于 Python 的文档构建器，您可以使用 python_append_deps 函数自动将 [${PYTHON_USEDEP}] 追加到其他依赖项。

Doxygen 使用示例

DOCS_BUILDER="doxygen"
DOCS_DEPEND="media-gfx/imagemagick"
DOCS_DIR="docs"

inherit docs

...

src_compile() {
        default
        docs_compile
}

使用 distutils-r1 的 Mkdocs 使用示例

DOCS_BUILDER="mkdocs"
DOCS_DEPEND="dev-python/mkdocs-material"
DOCS_DIR="doc"

PYTHON_COMPAT=( python3_{8..10} )

inherit distutils-r1 docs

...

支持的 EAPIS

7 8

函数

initialize_git_repo

初始化一个虚拟 Git 仓库。如果设置了 DOCS_INITIALIZE_GIT，则文档编译函数将调用此函数。也可以手动调用它。

sphinx_compile

调用 Sphinx 构建文档。

mkdocs_compile

调用 Mkdocs 构建文档。

doxygen_compile

调用 Doxygen 构建文档。

docs_compile

调用 DOCS_BUILDER 并设置 HTML_DOCS

此函数必须在 src_compile 中调用。注意不要覆盖它设置的变量。如果在继承此 eclass *之前* 继承了 distutils-r1，则 docs_compile 会自动添加到 python_compile_all() 中，无需手动调用它。请注意，此函数会检查 USE="doc" 是否已启用，如果未启用，则会自动退出。因此，无需将此函数包装在 if 语句中。

使用示例

src_compile() {
        default
        docs_compile
}

Eclass 变量

DOCS_BUILDER (必需) (在继承之前设置)

设置要使用的文档构建器，目前支持 Sphinx、Mkdocs 和 Doxygen。对于基于 Python 的文档构建器：Sphinx 和 Mkdocs，应设置 PYTHON_COMPAT

DOCS_DIR

包含文档构建器配置文件的路径。

对于 Sphinx，这是“conf.py”的位置

对于 Mkdocs，这是“mkdocs.yml”的位置。请注意，mkdocs.yml 通常不位于与实际文档文件相同的目录中

对于 Doxygen，默认名称为 Doxyfile，但软件包可能使用非标准名称。如果是这种情况，则应将 DOCS_CONFIG_NAME 设置为正确的名称

默认为 ${S}

DOCS_DEPEND (在继承之前设置)

设置构建文档所需的额外依赖项。对于 Sphinx 和 Mkdocs，这些依赖项应*不带* [${PYTHON_USEDEP}] 指定，eclass 会自动添加。例如，要依赖 mkdocs-material

DOCS_DEPEND="dev-python/mkdocs-material"

此 eclass 会追加到此变量，这使得以后在您的 ebuild 中再次调用它成为可能。

DOCS_AUTODOC (在继承之前设置)

设置是否使用 sphinx.ext.autodoc/mkautodoc。对于 Sphinx，默认为 1 (True)，对于 Mkdocs，默认为 0 (False)。与 Doxygen 无关。

DOCS_OUTDIR

设置应将文档构建到的目录。没有真正的理由更改此设置。但是，如果软件包也应该安装其他 HTML 文件，则此变量很有用。

使用示例

HTML_DOCS=( "${yourdocs}" "${DOCS_OUTDIR}/." )

默认为 ${S}/_build/html

DOCS_CONFIG_NAME

文档构建器配置文件的名称。

仅与 Doxygen 相关，因为它允许使用非标准名称的配置文件。对 Mkdocs 或 Sphinx 没有影响。

对于 Doxygen，默认为 Doxyfile

DOCS_INITIALIZE_GIT (在继承之前设置)

有时如果不在 Git 仓库中执行，构建文档将失败。如果设置了此变量，编译函数将在编译前初始化一个虚拟 Git 仓库。会自动添加对 dev-vcs/git 的依赖。

作者

作者：Andrew Ammerlaan <[email protected]>
基于以下人员的工作：Michał Górny <[email protected]>

维护者

Andrew Ammerlaan <[email protected]>

报告 Bug

请通过 https://bugs.gentoo.org/ 报告 Bug

文件

docs.eclass

另请参见

ebuild(5)
https://gitweb.gentoo.org/repo/gentoo.git/log/eclass/docs.eclass

本文件由 man2html 使用手册页创建。
时间：2024年11月12日，格林威治标准时间03:27:01