文档和示例

文档

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
```
注意

由于 xgboost_ray 在 conda 渠道中不可用，目前无法使用 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（简称 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：阅读文档标志。当设置为 True（区分大小写）时，构建完整的文档站点，包括 R、JVM 和 C 文档。

XGBOOST_R_DOCS：预构建 R 文档的本地路径，用于开发。如果它指向不存在的文件，配置脚本将把打包的文档下载到该路径以供将来重用。

XGBOOST_JVM_DOCS：预构建 JVM 文档的本地路径，用于开发。与 R 文档环境变量类似，当它指向不存在的文件时。

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

示例

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