文档

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-24.04-2024.06.17 \
    /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 文档，请考虑使用常用的 R 工具来生成文档。或者使用上面描述的基于 Docker 的方法在本地构建 R 文档。

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

如果您在安装 Doxygen 时遇到任何问题，或者您根本不需要 C 代码的文档，可以在不使用 Doxygen 的情况下构建文档

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