拓冰网站定制 
Megatron-LM 本地文档构建指南基于 uv 与 Sphinx 的完整开发工作流【免费下载链接】Megatron-LMOngoing research training transformer models at scale项目地址: https://gitcode.com/GitHub_Trending/me/Megatron-LM导读Megatron-LM 仓库使用 Sphinx 构建其开发者文档与 Python API 参考文档并借助uv的依赖组dependency groups机制管理文档工具链。本文以 docs/developer/generate_docs.md 为骨架结合 docs/conf.py、docs/documentation.md 与 pyproject.toml 的源码细节完整讲解本地文档构建、实时预览、链接检查与版本切换器的配置方法。读完后你将掌握一套可复制、可调试的 Megatron-LM 文档开发流程能够在本机独立构建出与官方一致的文档站点。一、文档体系概览Megatron-LM 的文档源文件全部位于仓库的docs/目录下采用 Markdown 编写并通过 Sphinx 的 MyST Parser 扩展解析渲染为 HTML。目录结构大致分为以下几类面向用户的手册docs/user-guide/、docs/get-started/、docs/models/开发者文档docs/developer/含generate_docs.md、contribute.md、submit.md等API 参考docs/api-guide/下的手写指南页以及由 autodoc2 自动生成的apidocs/站点配置docs/conf.py、docs/index.md、docs/versions1.json、docs/project.json。文档站点的导航结构定义在 docs/index.md 中它通过多个{toctree}指令将上述目录组织为“Get Started”“Basic Usage”“Advanced Features”“Developer Guide”“API Reference”等分组其中 Developer Guide 分组就包含了 docs/developer/generate_docs.md 这一页。二、环境准备uv 与 docs 依赖组2.1 依赖组定义Megatron-LM 使用uv管理 Python 依赖文档相关的依赖被集中定义在 pyproject.toml 的[dependency-groups]中的docs组docs [ sphinx, sphinx-autobuild, # For live doc serving while editing docs sphinx-autodoc2, # For documenting Python API sphinx-copybutton, # Adds a copy button for code blocks myst_parser, # For our markdown docs nvidia-sphinx-theme, # Our NVIDIA theme ]各依赖的职责如下依赖用途sphinx核心文档构建引擎sphinx-autobuild监听源文件变化并自动重建、实时刷新浏览器sphinx-autodoc2从megatron/core包源码自动生成 Python API 文档sphinx-copybutton为代码块添加一键复制按钮myst_parser让 Sphinx 直接解析 Markdown 源文件nvidia-sphinx-themeNVIDIA 官方文档主题提供版本切换器等站点特性这些依赖的精确版本由仓库根目录的uv.lock锁定因此无论何时在本地执行文档构建得到的工具链版本都是一致的。2.2--only-group docs的含义原文档给出的命令是cd docs SKIP_PUBLIC_DOCS_FEATUREStrue uv run --only-group docs sphinx-autobuild . _build/html --port 8080 --host 127.0.0.1其中--only-group docs是理解整个工作流的关键。在 pyproject.toml 中uv配置了默认依赖组[tool.uv] managed true default-groups [linting, build, test]这意味着普通的uv run会默认安装linting、build、test三个组的大量重型依赖包括 pytest、torch 相关构建工具等。而--only-group docs明确告诉 uv只安装docs这一个依赖组从而大幅缩短环境准备时间避免拉取与文档构建无关的包避免因 torch、transformer-engine 等重型包带来的环境冲突或安装失败。首次运行时uv 会在docs/目录命令的执行位置自动创建并配置虚拟环境。仓库根目录的uv.lock保证了所有文档依赖版本可复现。三、一次性构建静态文档3.1 基础构建命令如果不打算边编辑边预览可以直接使用sphinx-build生成静态 HTMLcd docs/ uv run --only-group docs sphinx-build . _build/html执行后生成的 HTML 文件输出到docs/_build/html/目录由 autodoc2 自动生成的 Python API 文档apidocs会输出到docs/apidocs/目录并被 docs/index.md 中的apidocs/index.rst通过 toctree 引用。_build与apidocs都属于构建产物docs/conf.py中通过exclude_patterns [_build, Thumbs.db, .DS_Store]将_build排除在源文件扫描之外。3.2 推荐设置SKIP_AUTODOCtrue原文档特别强调生成文档时推荐设置环境变量SKIP_AUTODOCtrue以跳过apidocs的生成。该变量的读取逻辑位于 docs/conf.pyskip_autodoc os.environ.get(SKIP_AUTODOC, false).lower() true if not skip_autodoc: extensions.append(autodoc2) # Generates API docs当SKIP_AUTODOCtrue时autodoc2 扩展不会被加载Sphinx 便不会遍历megatron/core包、解析所有 docstring 并渲染成 API 页面。这样做的收益是构建速度显著提升适合日常编写 Markdown 文档时的快速迭代避免因个别模块导入副作用或环境缺少 GPU 相关依赖而导致整个构建失败。当你需要完整文档含 API Reference时去掉该变量重新构建即可。四、实时预览sphinx-autobuild 开发模式编写文档时频繁手动执行构建再刷新浏览器非常低效。原文档给出的命令正是利用了sphinx-autobuild的监听能力cd docs SKIP_PUBLIC_DOCS_FEATUREStrue uv run --only-group docs sphinx-autobuild . _build/html --port 8080 --host 127.0.0.1命令逐段拆解片段作用SKIP_PUBLIC_DOCS_FEATUREStrue关闭站点上的“公开文档”特性开关详见下文 5.2uv run --only-group docs使用仅含 docs 依赖组的环境运行命令sphinx-autobuild . _build/html以docs/为源目录构建输出到_build/html--port 8080指定预览服务监听端口为 8080--host 127.0.0.1只绑定本机回环地址避免对外网暴露启动成功后在浏览器访问http://localhost:8080/即可查看文档站点。此后每次保存docs/下的 Markdown 源文件autobuild 都会自动触发增量重建浏览器页面也随之刷新形成即时反馈的编辑体验。若希望局域网内的其他机器也能访问预览站点可参照 docs/documentation.md 中的示例将 host 改为0.0.0.0并自定义端口cd docs/ uv run --group docs sphinx-autobuild . _build/html --port 12345 --host 0.0.0.0然后通过http://${HOST_WHERE_SPHINX_COMMAND_RUN}:12345访问。注意当指定--host 0.0.0.0时站点对局域网内所有主机可见仅在可信网络中使用。五、docs/conf.py 中的关键机制理解 docs/conf.py 的配置能帮助你在构建异常时快速定位问题。5.1 启用的 Sphinx 扩展extensions [ myst_parser, # For our markdown docs sphinx.ext.viewcode, # For adding a link to view source code in docs sphinx.ext.doctest, # Allows testing in docstrings sphinx.ext.napoleon, # For google style docstrings sphinx_copybutton, # For copy button in code blocks ]myst_parser让 Sphinx 解析 Markdown并启用了dollarmath、colon_fence、tasklist等一系列 MyST 扩展语法napoleon 自定义解析器仓库在 docs/autodoc2_docstrings_parser.py 中定义了一个NapoleonParser将GoogleDocstring转换逻辑注入 MyST 解析流程使得megatron/core源码中 Google 风格的 docstring 能被 autodoc2 正确渲染viewcode为 API 页面提供“查看源代码”跳转链接。5.2 SKIP_PUBLIC_DOCS_FEATURES 环境变量public_docs_features: os.environ.get(SKIP_PUBLIC_DOCS_FEATURES, false).lower() ! true,该变量控制nvidia_sphinx_theme主题中“公开文档”相关特性如版本切换器、GitHub 图标链接等的启用与否。默认值为false即启用公开特性原文档的命令将其显式设为true通常是本地预览时希望屏蔽对外发布相关的站点组件。5.3 autodoc2 的包扫描配置autodoc2_packages [ { path: ../megatron/core, exclude_dirs: [converters], } ] autodoc2_render_plugin myst autodoc2_output_dir apidocs当未设置SKIP_AUTODOC时autodoc2 会扫描megatron/core整个包排除converters子目录生成 API 文档到apidocs/并使用 MyST 渲染 docstring。此外配置还通过autodoc2_hidden_regexes排除了个别含正则字面量如\p{L}的变量避免 docutils 误解析。六、检查失效链接linkcheck文档质量的一个重要保障是外部链接的有效性。仓库在 docs/documentation.md 中提供了链接检查命令cd docs/ uv run --only-group docs sphinx-build --builder linkcheck . _build/linkcheck运行后Sphinx 会逐个请求文档中出现的 HTTP 链接并将结果输出为_build/linkcheck/output.json其中无法访问的链接会被标记为broken。需要特别说明的是 docs/conf.py 中的链接检查策略linkcheck_ignore [ .*github\\.com.*, .*githubusercontent\\.com.*, http://localhost.*, ] linkcheck_retries 10 linkcheck_rate_limit_timeout 600 linkcheck_workers 1由于 CI 环境下访问 GitHub 频繁遭遇 rate limit配置默认忽略所有 GitHub 相关链接同时设置重试 10 次、单链接超时 600 秒、单工作线程以应对慢速网络。若你希望完整检查包括 GitHub 在内的全部链接可以按 docs/documentation.md 的提示临时注释掉linkcheck_ignore后再执行。七、版本切换器与发布前的版本更新nvidia_sphinx_theme主题的版本切换器由三个文件协同控制文件作用docs/versions1.json定义版本列表每项包含name、version、url并可用preferred: true标记默认版本docs/project.json定义当前站点元信息如{name: megatron-lm, version: nightly}docs/conf.py通过html_theme_options[switcher]引用versions1.json并将html_extra_path设为[project.json, versions1.json]使其随站点一起发布从 docs/versions1.json 可以看到当前版本序列从nightly构建版本一直到0.15.0其中0.19.0被标记为 latest 默认版本。按照 docs/documentation.md 的说明在发布新版本文档之前需要同步更新这三个文件中的版本号确保切换器能正确指向新版本页面。八、常见问题与排查建议首次构建较慢或下载失败--only-group docs已是最小化安装若网络不稳定可先执行uv sync --only-group docs单独完成环境同步再运行构建命令必要时可配置 uv 镜像源。只想快速看 Markdown 页面但构建卡在 API 文档上始终带上SKIP_AUTODOCtrue跳过megatron/core的 docstring 解析。链接检查结果大量 broken 且都是 GitHub 域名这是 docs/conf.py 中 rate limit 策略的预期表现并非链接真的失效如需验证 GitHub 链接可临时注释linkcheck_ignore。预览页面无样式或缺少导航确认命令在docs/目录下执行sphinx-autobuild的第一个参数.指向当前目录并确保nvidia-sphinx-theme已随 docs 依赖组正确安装。新增 Markdown 页面未出现在站点中需要在 docs/index.md 相应的{toctree}分组中登记该页面路径Sphinx 才会将其纳入构建。九、总结Megatron-LM 的本地文档构建流程以uv依赖组隔离文档工具链以sphinx-autobuild提供实时预览以SKIP_AUTODOC与SKIP_PUBLIC_DOCS_FEATURES两个环境变量灵活控制构建范围辅以 linkcheck 和版本切换器保证站点质量。掌握 docs/developer/generate_docs.md 中的命令及其背后的 docs/conf.py 配置你便可以在本地完整复现、调试和扩展 Megatron-LM 的官方文档站点为后续文档贡献参见 docs/developer/contribute.md打下坚实基础。【免费下载链接】Megatron-LMOngoing research training transformer models at scale项目地址: https://gitcode.com/GitHub_Trending/me/Megatron-LM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Megatron-LM 本地文档构建指南：基于 uv 与 Sphinx 的完整开发工作流
Megatron-LM 本地文档构建指南基于 uv 与 Sphinx 的完整开发工作流【免费下载链接】Megatron-LMOngoing research training transformer models at scale项目地址: https://gitcode.com/GitHub_Trending/me/Megatron-LM导读Megatron-LM 仓库使用 Sphinx 构建其开发者文档与 Python API 参考文档并借助uv的依赖组dependency groups机制管理文档工具链。本文以 docs/developer/generate_docs.md 为骨架结合 docs/conf.py、docs/documentation.md 与 pyproject.toml 的源码细节完整讲解本地文档构建、实时预览、链接检查与版本切换器的配置方法。读完后你将掌握一套可复制、可调试的 Megatron-LM 文档开发流程能够在本机独立构建出与官方一致的文档站点。一、文档体系概览Megatron-LM 的文档源文件全部位于仓库的docs/目录下采用 Markdown 编写并通过 Sphinx 的 MyST Parser 扩展解析渲染为 HTML。目录结构大致分为以下几类面向用户的手册docs/user-guide/、docs/get-started/、docs/models/开发者文档docs/developer/含generate_docs.md、contribute.md、submit.md等API 参考docs/api-guide/下的手写指南页以及由 autodoc2 自动生成的apidocs/站点配置docs/conf.py、docs/index.md、docs/versions1.json、docs/project.json。文档站点的导航结构定义在 docs/index.md 中它通过多个{toctree}指令将上述目录组织为“Get Started”“Basic Usage”“Advanced Features”“Developer Guide”“API Reference”等分组其中 Developer Guide 分组就包含了 docs/developer/generate_docs.md 这一页。二、环境准备uv 与 docs 依赖组2.1 依赖组定义Megatron-LM 使用uv管理 Python 依赖文档相关的依赖被集中定义在 pyproject.toml 的[dependency-groups]中的docs组docs [ sphinx, sphinx-autobuild, # For live doc serving while editing docs sphinx-autodoc2, # For documenting Python API sphinx-copybutton, # Adds a copy button for code blocks myst_parser, # For our markdown docs nvidia-sphinx-theme, # Our NVIDIA theme ]各依赖的职责如下依赖用途sphinx核心文档构建引擎sphinx-autobuild监听源文件变化并自动重建、实时刷新浏览器sphinx-autodoc2从megatron/core包源码自动生成 Python API 文档sphinx-copybutton为代码块添加一键复制按钮myst_parser让 Sphinx 直接解析 Markdown 源文件nvidia-sphinx-themeNVIDIA 官方文档主题提供版本切换器等站点特性这些依赖的精确版本由仓库根目录的uv.lock锁定因此无论何时在本地执行文档构建得到的工具链版本都是一致的。2.2--only-group docs的含义原文档给出的命令是cd docs SKIP_PUBLIC_DOCS_FEATUREStrue uv run --only-group docs sphinx-autobuild . _build/html --port 8080 --host 127.0.0.1其中--only-group docs是理解整个工作流的关键。在 pyproject.toml 中uv配置了默认依赖组[tool.uv] managed true default-groups [linting, build, test]这意味着普通的uv run会默认安装linting、build、test三个组的大量重型依赖包括 pytest、torch 相关构建工具等。而--only-group docs明确告诉 uv只安装docs这一个依赖组从而大幅缩短环境准备时间避免拉取与文档构建无关的包避免因 torch、transformer-engine 等重型包带来的环境冲突或安装失败。首次运行时uv 会在docs/目录命令的执行位置自动创建并配置虚拟环境。仓库根目录的uv.lock保证了所有文档依赖版本可复现。三、一次性构建静态文档3.1 基础构建命令如果不打算边编辑边预览可以直接使用sphinx-build生成静态 HTMLcd docs/ uv run --only-group docs sphinx-build . _build/html执行后生成的 HTML 文件输出到docs/_build/html/目录由 autodoc2 自动生成的 Python API 文档apidocs会输出到docs/apidocs/目录并被 docs/index.md 中的apidocs/index.rst通过 toctree 引用。_build与apidocs都属于构建产物docs/conf.py中通过exclude_patterns [_build, Thumbs.db, .DS_Store]将_build排除在源文件扫描之外。3.2 推荐设置SKIP_AUTODOCtrue原文档特别强调生成文档时推荐设置环境变量SKIP_AUTODOCtrue以跳过apidocs的生成。该变量的读取逻辑位于 docs/conf.pyskip_autodoc os.environ.get(SKIP_AUTODOC, false).lower() true if not skip_autodoc: extensions.append(autodoc2) # Generates API docs当SKIP_AUTODOCtrue时autodoc2 扩展不会被加载Sphinx 便不会遍历megatron/core包、解析所有 docstring 并渲染成 API 页面。这样做的收益是构建速度显著提升适合日常编写 Markdown 文档时的快速迭代避免因个别模块导入副作用或环境缺少 GPU 相关依赖而导致整个构建失败。当你需要完整文档含 API Reference时去掉该变量重新构建即可。四、实时预览sphinx-autobuild 开发模式编写文档时频繁手动执行构建再刷新浏览器非常低效。原文档给出的命令正是利用了sphinx-autobuild的监听能力cd docs SKIP_PUBLIC_DOCS_FEATUREStrue uv run --only-group docs sphinx-autobuild . _build/html --port 8080 --host 127.0.0.1命令逐段拆解片段作用SKIP_PUBLIC_DOCS_FEATUREStrue关闭站点上的“公开文档”特性开关详见下文 5.2uv run --only-group docs使用仅含 docs 依赖组的环境运行命令sphinx-autobuild . _build/html以docs/为源目录构建输出到_build/html--port 8080指定预览服务监听端口为 8080--host 127.0.0.1只绑定本机回环地址避免对外网暴露启动成功后在浏览器访问http://localhost:8080/即可查看文档站点。此后每次保存docs/下的 Markdown 源文件autobuild 都会自动触发增量重建浏览器页面也随之刷新形成即时反馈的编辑体验。若希望局域网内的其他机器也能访问预览站点可参照 docs/documentation.md 中的示例将 host 改为0.0.0.0并自定义端口cd docs/ uv run --group docs sphinx-autobuild . _build/html --port 12345 --host 0.0.0.0然后通过http://${HOST_WHERE_SPHINX_COMMAND_RUN}:12345访问。注意当指定--host 0.0.0.0时站点对局域网内所有主机可见仅在可信网络中使用。五、docs/conf.py 中的关键机制理解 docs/conf.py 的配置能帮助你在构建异常时快速定位问题。5.1 启用的 Sphinx 扩展extensions [ myst_parser, # For our markdown docs sphinx.ext.viewcode, # For adding a link to view source code in docs sphinx.ext.doctest, # Allows testing in docstrings sphinx.ext.napoleon, # For google style docstrings sphinx_copybutton, # For copy button in code blocks ]myst_parser让 Sphinx 解析 Markdown并启用了dollarmath、colon_fence、tasklist等一系列 MyST 扩展语法napoleon 自定义解析器仓库在 docs/autodoc2_docstrings_parser.py 中定义了一个NapoleonParser将GoogleDocstring转换逻辑注入 MyST 解析流程使得megatron/core源码中 Google 风格的 docstring 能被 autodoc2 正确渲染viewcode为 API 页面提供“查看源代码”跳转链接。5.2 SKIP_PUBLIC_DOCS_FEATURES 环境变量public_docs_features: os.environ.get(SKIP_PUBLIC_DOCS_FEATURES, false).lower() ! true,该变量控制nvidia_sphinx_theme主题中“公开文档”相关特性如版本切换器、GitHub 图标链接等的启用与否。默认值为false即启用公开特性原文档的命令将其显式设为true通常是本地预览时希望屏蔽对外发布相关的站点组件。5.3 autodoc2 的包扫描配置autodoc2_packages [ { path: ../megatron/core, exclude_dirs: [converters], } ] autodoc2_render_plugin myst autodoc2_output_dir apidocs当未设置SKIP_AUTODOC时autodoc2 会扫描megatron/core整个包排除converters子目录生成 API 文档到apidocs/并使用 MyST 渲染 docstring。此外配置还通过autodoc2_hidden_regexes排除了个别含正则字面量如\p{L}的变量避免 docutils 误解析。六、检查失效链接linkcheck文档质量的一个重要保障是外部链接的有效性。仓库在 docs/documentation.md 中提供了链接检查命令cd docs/ uv run --only-group docs sphinx-build --builder linkcheck . _build/linkcheck运行后Sphinx 会逐个请求文档中出现的 HTTP 链接并将结果输出为_build/linkcheck/output.json其中无法访问的链接会被标记为broken。需要特别说明的是 docs/conf.py 中的链接检查策略linkcheck_ignore [ .*github\\.com.*, .*githubusercontent\\.com.*, http://localhost.*, ] linkcheck_retries 10 linkcheck_rate_limit_timeout 600 linkcheck_workers 1由于 CI 环境下访问 GitHub 频繁遭遇 rate limit配置默认忽略所有 GitHub 相关链接同时设置重试 10 次、单链接超时 600 秒、单工作线程以应对慢速网络。若你希望完整检查包括 GitHub 在内的全部链接可以按 docs/documentation.md 的提示临时注释掉linkcheck_ignore后再执行。七、版本切换器与发布前的版本更新nvidia_sphinx_theme主题的版本切换器由三个文件协同控制文件作用docs/versions1.json定义版本列表每项包含name、version、url并可用preferred: true标记默认版本docs/project.json定义当前站点元信息如{name: megatron-lm, version: nightly}docs/conf.py通过html_theme_options[switcher]引用versions1.json并将html_extra_path设为[project.json, versions1.json]使其随站点一起发布从 docs/versions1.json 可以看到当前版本序列从nightly构建版本一直到0.15.0其中0.19.0被标记为 latest 默认版本。按照 docs/documentation.md 的说明在发布新版本文档之前需要同步更新这三个文件中的版本号确保切换器能正确指向新版本页面。八、常见问题与排查建议首次构建较慢或下载失败--only-group docs已是最小化安装若网络不稳定可先执行uv sync --only-group docs单独完成环境同步再运行构建命令必要时可配置 uv 镜像源。只想快速看 Markdown 页面但构建卡在 API 文档上始终带上SKIP_AUTODOCtrue跳过megatron/core的 docstring 解析。链接检查结果大量 broken 且都是 GitHub 域名这是 docs/conf.py 中 rate limit 策略的预期表现并非链接真的失效如需验证 GitHub 链接可临时注释linkcheck_ignore。预览页面无样式或缺少导航确认命令在docs/目录下执行sphinx-autobuild的第一个参数.指向当前目录并确保nvidia-sphinx-theme已随 docs 依赖组正确安装。新增 Markdown 页面未出现在站点中需要在 docs/index.md 相应的{toctree}分组中登记该页面路径Sphinx 才会将其纳入构建。九、总结Megatron-LM 的本地文档构建流程以uv依赖组隔离文档工具链以sphinx-autobuild提供实时预览以SKIP_AUTODOC与SKIP_PUBLIC_DOCS_FEATURES两个环境变量灵活控制构建范围辅以 linkcheck 和版本切换器保证站点质量。掌握 docs/developer/generate_docs.md 中的命令及其背后的 docs/conf.py 配置你便可以在本地完整复现、调试和扩展 Megatron-LM 的官方文档站点为后续文档贡献参见 docs/developer/contribute.md打下坚实基础。【免费下载链接】Megatron-LMOngoing research training transformer models at scale项目地址: https://gitcode.com/GitHub_Trending/me/Megatron-LM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考