ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

NVIDIA cuML 文档构建指南:使用 build.sh 一站式生成 C++ Doxygen 与 Python Sphinx 文档

NVIDIA cuML 文档构建指南:使用 build.sh 一站式生成 C++ Doxygen 与 Python Sphinx 文档 NVIDIA cuML 文档构建指南使用 build.sh 一站式生成 C Doxygen 与 Python Sphinx 文档【免费下载链接】cumlNVIDIA cuML: GPU-Accelerated Machine Learning项目地址: https://gitcode.com/GitHub_Trending/cu/cumlcuMLNVIDIA GPU 加速机器学习库的官方文档由两层组成面向 C/C 源码的 Doxygen API 文档以及面向 Python 用户指南与 API 参考的 Sphinx 文档。本文以仓库中的 docs/README.md 为主线完整讲解如何在本地从源码构建并查看 cuML 全量文档并深入到 build.sh、ci/build_docs.sh、docs/source/conf.py 与 cpp/Doxyfile.in 等实现细节帮助你理解文档系统的生成原理、目录结构、依赖与常见配置从而能独立完成本地文档构建、增量更新与问题排查。一、cuML 文档体系概览cuML 的文档并非单一文件而是由两条独立的生成链路组成最终汇聚成一套完整的站点文档类型面向对象生成工具配置入口C API 文档libcuml 的 C 头文件与源码Doxygencpp/Doxyfile.inPython 与通用文档用户指南、API 参考、notebook、博客等Sphinxdocs/source/conf.py文档源文件统一存放在仓库的 docs/source 目录下其中docs/source/index.rst 是文档站点首页包含 Quick Start 代码示例、Key Features、Installation 等介绍并通过 toctree 组织cuml_intro、user_guide、cuml-accel与api/index等子页面docs/source/user_guide.rst 汇集了 estimator_intro.ipynb、dask_multigpu_guide.ipynb、advanced.rst、health_checks.rst 与 supported_versions.rst 等实操指南docs/source/api/index.rst 是完整的 API 参考索引按模块罗列了聚类、回归/分类、降维、协方差估计、时间序列、可解释性与多节点多 GPU 等全部 estimator并托管了cuml.accel的加速相关接口。本文核心文档 docs/README.md 给出的构建流程只有三步先构建并安装 cuML再运行build.sh cppdocs pydocs生成文档最后用浏览器打开build/html/api.html查看。下面逐节展开每一步背后的细节。二、构建前置条件先构建并安装 cuML生成 Python 文档依赖 cuML Python 包能够被正常导入docs/source/conf.py 中import cuml用于解析版本号因此文档构建前必须先完成 cuML 本身的编译与安装。完整的从源码构建步骤请参见仓库根目录的 BUILD.md其中明确列出了构建 libcuml C 库与 Python 包的命令运行时依赖的版本要求numpy、scikit-learn、scipy、joblib、numba、cupy、treelite 等详见 docs/source/supported_versions.rst环境变量与 CMake 选项PARALLEL_LEVEL、CUML_EXTRA_CMAKE_ARGS、CUML_EXTRA_PYTHON_ARGS等。另外docs/README.md 中给出的链接[Build and install cuML](https://link.gitcode.com/i/c58d8e282a5795a3f6891b341d559787)对应到仓库根目录即为 BUILD.md建议在开始生成文档前先通读该文件并完成 cuML 的本地安装。三、一条命令生成全部文档bash build.sh cppdocs pydocs按 docs/README.md 的指引在仓库根目录执行bash build.sh cppdocs pydocs这条命令会依次完成两件事其实现位于 build.sh 中cppdocs构建 C API 的 Doxygen 文档。对应 build.sh 中的逻辑if (! hasArg --configure-only) hasArg cppdocs; then cmake --build ${LIBCUML_BUILD_DIR} --target docs_cuml fi它调用 CMake 构建名为docs_cuml的自定义目标见下文第四节本质上是执行 Doxygen 解析全部 C/C 头文件与源码。pydocs构建 Python 与通用文档。对应 build.sh 中的逻辑先通过pip install安装python/cuml包再进入docs目录执行make htmlSKBUILD_CMAKE_ARGS-DCMAKE_MESSAGE_LOG_LEVEL${CMAKE_LOG_LEVEL};${SKBUILD_EXTRA_CMAKE_ARGS} \ python -m pip install ${PYTHON_ARGS_FOR_INSTALL[]} ${CUML_EXTRA_PYTHON_ARGS[]} ${REPODIR}/python/cuml if hasArg pydocs; then cd ${REPODIR}/docs make html fimake html由 docs/Makefile 定义其中SOURCEDIR source、BUILDDIR build并默认携带SPHINXOPTS -W——即把 Sphinx 告警视为错误保证文档质量。文档输出位置按 docs/README.md 的说明构建完成后文档位于build/html即 docs/build/html 目录下可用系统默认浏览器直接打开xdg-open build/html/api.html其中api.html是旧版 API 页面的产物在当前的 Sphinx 配置下docs/Makefile 将BUILDDIR指向docs/build而 docs/source/index.rst 将首页组织为index等独立目录页CI 中甚至使用dirhtml模式生成目录式页面因此实际入口通常为docs/build/html/index.html。若你的桌面环境不支持xdg-open也可以把该路径粘贴到任意浏览器地址栏打开。两种 target 也可单独执行build.sh 将cppdocs与pydocs定义为两个独立 targetcppdocs—— build the C API doxygen documentationpydocs—— build the general and Python API documentation。如果只修改了 C 头文件注释可以只跑bash build.sh cppdocs如果只调整了 RST 源文件可以只跑bash build.sh pydocs以缩短迭代周期。四、C 文档Doxygen 配置与生成原理C 文档的生成由 Doxygen 完成配置模板是 cpp/Doxyfile.in。其中值得关注的关键项包括OUTPUT_DIRECTORY空使用默认值配合GENERATE_HTML YES与HTML_OUTPUT htmlHTML 输出到运行目录下的html/子目录HTML_HEADER header.html指定自定义 HTML 页头即 cpp/header.htmlHTML_FILE_EXTENSION .html与GENERATE_HTMLHELP NO等默认输出行为。Doxyfile.in是模板文件真正的生成入口在 cpp/cmake/doxygen.cmake 中CMake 通过find_package(Doxygen 1.9.1)探测 Doxygen并将Doxyfile.in以ONLY模式配置为实际Doxyfile随后注册名为docs_cuml的自定义目标在执行时设置RAPIDS_VERSION与RAPIDS_VERSION_MAJOR_MINOR环境变量并调用 Doxygenadd_custom_target( docs_cuml ${CMAKE_COMMAND} -E env RAPIDS_VERSION${RAPIDS_VERSION} RAPIDS_VERSION_MAJOR_MINOR${RAPIDS_VERSION_MAJOR_MINOR} ${DOXYGEN_EXECUTABLE} ${dox_OUT_DOXYFILE} WORKING_DIRECTORY ${dox_CWD} VERBATIM COMMENT Generate doxygen docs )从源码结构看Doxygen 会遍历 cpp/include/cumlcluster、decomposition、ensemble、linear_model、manifold、metrics、neighbors、svm、tree、tsa 等模块的公开头文件以及 cpp/src 下的实现文件为全部 C 公共 API 生成带继承关系、函数签名与注释的参考文档。除了build.sh cppdocs之外BUILD.md 还提供了另一种等价方式——在cpp/build目录下执行$ make doc两种方式最终都落到docs_cuml这个 Doxygen 目标上。五、Python 文档Sphinx 配置体系Python 与通用文档由 Sphinx 构建核心配置在 docs/source/conf.py 中构建入口是 docs/Makefile。这一节拆解其关键机制方便你在本地构建时理解每个环节。5.1 构建命令与目录约定docs/Makefile 是极简的 Sphinx MakefileSPHINXOPTS -W SPHINXBUILD sphinx-build SPHINXPROJ cuML SOURCEDIR source BUILDDIR buildmake html等价于sphinx-build -W -M html source build-W表示将 warning 升级为 error。因此文档源文件若有遗漏的引用或错误的 cross-reference构建会直接失败并给出明确报错这也是官方文档质量较高的原因之一。5.2 conf.py 的关键配置conf.py 中值得了解的配置项扩展列表conf.py#L45-L59numpydoc、sphinx.ext.autodoc、sphinx.ext.autosummary、sphinx.ext.intersphinx、sphinx.ext.linkcode以及nbsphinx渲染 notebook、recommonmark、sphinx_markdown_tables、sphinx_copybutton、sphinx_design、IPython.sphinxext.ipython_directive等。这意味着文档源既支持 RST.rst也支持 Markdown.md与 notebook.ipynbsource_suffix {.rst: restructuredtext, .md: markdown}显式声明了这两种后缀。版本号解析conf.py#L87-L93通过import cuml读取cuml.__version__拼出version如25.02与release如25.02.00——这正是为什么必须先安装 cuML Python 包才能构建 Python 文档。主题与站点装饰conf.py#L119-L145使用nvidia_sphinx_theme并配置版本切换器、导航栏等静态资源放在 docs/source/_static。交叉引用conf.py#L213-L227通过intersphinx_mapping关联 cudf、numpy、python、sklearn、cupy、cuda.core、rmm 的在线文档让文档中的外部类型引用可以跳转。源码链接conf.py#L280-L286linkcode_resolve配合 docs/source/sphinxext/github_link.py为每个 API 对象生成指向python/cuml/...源码的跳转链接。重定向conf.py#L235-L277setup_redirects在构建完成时把旧版零代码加速zero-code-change页面重定向到新的 docs/source/cuml-accel 目录保证历史 URL 不失效。5.3 文档内容组织docs/source/index.rst站点首页内含 Quick Start 示例cuml.datasets.make_blobscuml.cluster.DBSCAN聚类演示与 Key Features 列表并通过隐藏 toctree 串联cuml_intro.rst、user_guide.rst、cuml-accel/index.rst、api/index与cuml_blogs.rst。docs/source/user_guide.rst用户指南目录逐项链接 estimator 入门 notebook、模型序列化pickling、Dask 多 GPU 指南、进阶主题与健康检查。docs/source/api/index.rstAPI 参考总索引按「Output Data Type Configuration」「Regression and Classification」「Clustering」「Dimensionality Reduction and Manifold Learning」「Multi-Node, Multi-GPU Algorithms」「cuml.accel」等分区组织并引用 docs/source/api/cuml.rst 等各模块页面。六、CI 中的文档构建流程仓库的持续集成通过 ci/build_docs.sh 构建并发布文档其流程可作为本地构建的参照从 CI 产物仓库下载 libcuml 与 cuml 的 conda 包并用rapids-dependency-file-generator按docs依赖组合成env.yaml创建名为docs的 conda 环境进入cpp目录执行doxygen Doxyfile.in生成 C 文档并移动到$RAPIDS_DOCS_DIR/libcuml/html进入docs目录执行sphinx-build -b dirhtml ./source _html -W生成 Python 文档并移动到$RAPIDS_DOCS_DIR/cuml/html最后通过rapids-upload-docs将两份文档上传发布。与本地build.sh相比CI 的差异点在于使用dirhtml模式输出目录式页面便于托管、直接调用底层命令而非封装脚本、以及把 C 与 Python 文档分离到不同子目录。这也解释了 docs/source/conf.py 中if app.builder.name dirhtml的判据来源。七、查看文档与常见问题排查7.1 打开文档构建完成后按 docs/README.md 的说明执行xdg-open build/html/api.html实际目录为 docs/build/html由 docs/Makefile 的BUILDDIR build决定。若只想浏览最新的 API 参考直接打开docs/build/html/index.html或docs/build/html/api/index.html即可。7.2 常见问题pydocs 构建失败并报 warningSPHINXOPTS -W将告警视为错误请根据报错信息修复 RST 源文件中的无效引用如果只是临时查看也可手动执行sphinx-build -M html source build去掉-W绕过。import cuml失败pydocs 需要可导入的 cuML 包来解析版本号请先完成 BUILD.md 中的安装步骤或在已激活的 conda 环境中确保cuml已安装。Doxygen 未找到docs_cuml目标依赖Doxygen 1.9.1见 cpp/cmake/doxygen.cmake请先通过系统包管理器或 conda 安装 Doxygen。只想重新生成部分文档分别使用bash build.sh cppdocs或bash build.sh pydocs结合-vverbose、--configure-only、--ccache等 build.sh 提供的 flag 可以控制构建行为。八、小结cuML 的文档体系是「Doxygen Sphinx」双引擎架构的典型实践C API 由 cpp/Doxyfile.in 与docs_cuml自定义目标驱动Python 与通用文档由 docs/Makefile 与 docs/source/conf.py 驱动两者通过仓库根目录的 build.sh 统一封装为cppdocs/pydocs两个 target。掌握bash build.sh cppdocs pydocs这条命令以及输出目录build/html、-W严格告警、Doxygen 版本要求等关键细节即可在本地完整复现官方文档构建流程如需进一步了解 cuML 的安装步骤与自定义构建选项可继续阅读 BUILD.md或直接浏览 docs/source 下的各 RST 源文件。【免费下载链接】cumlNVIDIA cuML: GPU-Accelerated Machine Learning项目地址: https://gitcode.com/GitHub_Trending/cu/cuml创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表