文档

LightGBM 的文档是使用 Sphinx 和 Breathe 生成的，后者基于 Doxygen 的输出工作。

Parameters.rst 中的参数列表及其描述是根据 配置文件 中的注释通过 此脚本 自动生成的。

每次在 master 上提交后，文档都会更新并发布到 Read the Docs。

构建

在修改 LightGBM 的源代码时，没有必要重新构建此文档。使用 Sphinx 生成的 HTML 文件不会被检入源代码控制。然而，在开发过程中，您可能希望在本地构建它们以测试更改。

Docker

在本地构建文档最可靠的方法是使用 Docker，使用 Read the Docs 使用的相同镜像。

从该仓库的根目录运行以下命令，以拉取相关镜像并在本地运行一个容器。

docker run \
    --rm \
    --user=0 \
    -v $(pwd):/opt/LightGBM \
    --env C_API=true \
    --env CONDA=/opt/miniforge \
    --env READTHEDOCS=true \
    --workdir=/opt/LightGBM/docs \
    --entrypoint="" \
    readthedocs/build:ubuntu-20.04-2021.09.23 \
    /bin/bash build-docs.sh

当代码完成后，在浏览器中打开 docs/_build/html/index.html。

备注

在这些本地构建的文档中，导航不会链接到本地复制的 R 文档。要查看 R 文档的本地版本，请在浏览器中打开 docs/_build/html/R/index.html。

不使用 Docker

你可以在没有 Docker 的情况下本地构建文档。只需安装 Doxygen 并在 docs 文件夹中运行。

pip install breathe sphinx 'sphinx_rtd_theme>=0.5'
make html

请注意，这不会构建 R 文档。如果需要，请考虑使用常见的 R 文档生成工具。或者使用上述基于 Docker 的方法在本地构建 R 文档。

可选地，您还可以安装 scikit-learn 并获取 Scikit-learn API 中类的更丰富的文档。

如果你在安装 Doxygen 时遇到任何问题，或者你根本不需要为 C 代码生成文档，那么可以不使用它来构建文档：

pip install sphinx 'sphinx_rtd_theme>=0.5'
export C_API=NO || set C_API=NO
make html