文档和示例

文档

Python 和 C 文档使用 Sphinx 构建。
每份文档都使用 reStructuredText 编写。
文档位于 doc/ 目录下。
您可以使用 make html 命令在本地构建它。
```
make html
```
运行 make help 了解其他命令。

在线文档由 Read the Docs 托管，导入的项目由 Hyunsu Cho 和 Jiaming Yuan 管理。

使用 pip 和 Conda 构建 Python 文档

创建一个 conda 环境。
```
conda create -n xgboost-docs --yes python=3.10
```
注意

xgboost_ray 包需要 Python 3.10。
激活环境
```
conda activate xgboost-docs
```
使用 pip 命令安装所需的包（在当前环境中）。
```
pip install -r requirements.txt
```
注意

目前无法使用 conda 安装所需的包，因为 xgboost_ray 在 conda 通道中不可用。
```
conda install --file requirements.txt --yes -c conda-forge
```
（可选）安装 graphviz
```
conda install graphviz --yes
```
最后，构建文档。
```
make html
```

您应该在控制台中看到以下消息

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v6.2.1
...
The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.

Read The Docs

Read the Docs（简称 RTD）是一个在线文档托管服务，托管着 XGBoost 文档网站。RTD 使用的文档构建器相对轻量。然而，一些包，例如 R 绑定，需要编译后的 XGBoost 以及所有可选依赖项来渲染文档。因此，基于 jvm 的包和 R 包的文档都是通过独立的 CI 流水线构建的，并在在线文档构建期间获取。

Sphinx 配置文件 xgboost/doc/conf.py 用作获取器。构建期间，获取到的构建产物分别存储在 xgboost/doc/tmp/jvm_docs 和 xgboost/doc/tmp/r_docs 中。对于 R 包，在 xgboost/doc/R-package/r_docs 中有一个虚拟索引文件。Jvm 文档类似。至于 C 文档，它使用 doxygen 生成并在构建期间由 breathe 处理，因为这相对简单。生成的 xml 文件存储在 xgboost/doc/tmp/dev 中。

xgboost/doc/tmp 是 conf.py 文件中指定的 html_extra_path Sphinx 配置的一部分，它通知 Sphinx 将提取的 html 文件复制到构建目录。以下是 conf.py 中获取器使用的环境变量列表

READTHEDOCS: Read the Docs 标志。当设置为 True 时（区分大小写），构建完整的文档站点，包括 R、JVM 和 C 文档。

XGBOOST_R_DOCS: 预构建 R 文档的本地路径，用于开发。

XGBOOST_JVM_DOCS: 预构建 JVM 文档的本地路径，用于开发。

截至撰写本文时，RTD 不提供任何可嵌入为 GitHub Actions 的功能，但我们需要一种方法来指定 CI 流水线和文档构建之间的依赖关系，以便获取正确的构建产物。解决方法是使用额外的 GA 步骤通过其 REST API 通知 RTD。

示例

用例和示例位于 demo 目录中。
我们非常期待听到您的故事。如果您有使用 XGBoost 的博客文章、教程或代码解决方案，请告诉我们，我们会在示例页面中添加链接。