Hydra 文档体系实战用 towncrier 管理 NEWS.md用 Docusaurus 构建官方站点【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydraHydra 仓库的文档基础设施由两部分组成一是基于 towncrier 的 NEWS.md 变更日志流水线贡献者只需提交小型 news fragment 文件发布时自动聚合渲染二是基于 Docusaurus 3 pnpm 的官方文档站点支持本地开发、静态构建与自动部署。读完本文你将掌握 Hydra 中新闻片段的分类规则与放置约定、pnpm 工作区对依赖发布的稳定性策略以及站点从pnpm start到 Netlify 部署的完整链路。一、NEWS.md 由 towncrier 统一管理Hydra 的 NEWS.md 并不由开发者手工维护而是交给 towncrier 中定义了完整的片段规范文件名以对应的 issue 或 PR 编号命名扩展名为类别名例如news/1234.bugfix放置位置Hydra 核心变更放根目录 news/插件变更放对应插件的news/目录例如plugins/hydra_optuna_sweeper/news/1234.feature多类别变更一个 PR 可以同时包含多个片段。比如既新增功能又弃用旧接口就同时创建news/1234.feature和news/1234.api_change如果一次变更涉及多个 issue 编号可以为每个编号各建一个内容相同的片段发布工具在渲染时会去重文风要求片段应简洁、面向用户使用句子式大小写sentence case、不超过 80 字符、祈使语气且要能补全句子 This change will ...片段文本中不需要写 issue/PR 编号引用链接由发布工具自动追加。当前仓库根目录的 news/ 目录就是这套机制的现场目录下有大量形如2928.bugfix、3206.feature、3287.api_change的待发布片段等待下一次 release 聚合进 NEWS.md。1.1 towncrier 配置项解读towncrier 的全部配置位于 pyproject.toml 的[tool.towncrier]段[tool.towncrier] package hydra package_dir filename NEWS.md directory news/ title_format {version} ({project_date}) template news/_template.rst issue_format #{issue} start_string !-- TOWNCRIER --\n各字段的实际含义配置值作用filenameNEWS.md生成的变更日志目标文件directorynews/收集新闻片段的目录title_format{version} ({project_date})每个版本标题的格式即1.3.2 (2023-02-22)这样的版本号 (日期)形式templatenews/_template.rst渲染所用的 Jinja2 模板见下文issue_format#{issue}片段后自动附加的 issue 链接格式start_string!-- TOWNCRIER --NEWS.md 中的标记注释towncrier 只在该标记之前插入新版本记录同一配置段还通过[[tool.towncrier.type]]声明了受支持的片段类别与 CONTRIBUTING.md 的约定一一对应扩展名渲染标题说明featureFeatures新功能api_changeAPI Change (Renames, deprecations and removals)API 变更、重命名、弃用与移除bugfixBug Fixes缺陷修复pluginPlugins插件相关变更configConfiguration structure changes配置结构变化docsImproved Documentation文档改进maintenanceMaintenance Changes可维护性改进1.2 渲染模板与最终效果渲染逻辑由 news/_template.rst 控制。它是一个 Jinja2 模板按 section 迭代对每个类别输出### {{ definitions[category][name] }}小节再把该类别下所有片段逐条以列表项输出对非plugin/process类别条目后会追加排序后的 issue 引用。若某类别为空则输出 No significant changes.。打开 NEWS.md 可以看到渲染后的真实结果例如1.3.2 (2023-02-22)版本下按 Features、Maintenance Changes 分节每条变更都带有指向对应 issue 的链接——这正是issue_format与模板共同作用的产物。从源码结构看仓库的tools/release/目录提供了 release 脚本与配套测试tools/release/release.py、tools/release/test_release.py发布流程会在打 tag 时驱动 towncrier 完成片段聚合与清理。二、网站搭建Docusaurus 3 pnpmHydra 的官方文档站点位于 website/ 目录基于 Docusaurus 3 构建website/README.md 中说明的版本要求为 Node.js 24 与 Python 3.10Python 用于在站点命令执行前运行确定性的 Hydra Landscape 生成器。2.1 安装与本地开发所有命令都在website目录下执行通过 corepack 统一 pnpm 版本$ corepack pnpm install安装完成后启动本地开发服务器$ corepack pnpm start从 website/package.json 的 scripts 定义可以看到start实际是start: node scripts/run-landscape-generator.mjs docusaurus start --port 9134也就是说pnpm start会先运行 Landscape 数据生成脚本再启动 Docusaurus 开发服务器固定端口 9134并打开浏览器窗口大多数修改无需重启即可热更新生效。pnpm build同样会先生成 Landscape 数据再把静态内容输出到build/目录可交由任意静态托管服务部署新增页面放入docs/后可经http://localhost:9134/docs/page_name本地访问。部署则全自动完成网站变更合入 main 分支后自动发布构建环境由 netlify.toml 固定为NODE_VERSION 24并使用--frozen-lockfile安装。2.2 pnpm 工作区的依赖稳定性策略文档中提到pnpm 被配置为在依赖更新时避免解析最近 10 天内发布的 npm 包版本这一策略的具体实现就在 website/pnpm-workspace.yamlminimumReleaseAge: 14400即 14400 分钟10 天包版本发布未满 10 天不会被解析选中以此规避刚发布即出现问题的包minimumReleaseAgeExclude为一批经过审查的包如js-yaml4.3.1、qs6.15.2豁免该限制overrides对 Babel、webpack、express、dompurify 等供应链关键包做版本锁定allowBuilds/strictDepBuilds禁用core-js、core-js-pure的构建脚本并启用严格依赖构建收紧安装期执行面patchedDependencies将image-size2.0.2指向patches/image-size2.0.2.patch以本地补丁修复该包的安全公告同时在auditConfig.ignoreGhsas中忽略对应编号并注释说明原因。package.json还声明了packageManager: pnpm11.21.0与engines: {node: 24}配合 corepack 保证团队成员与 CI 使用同一 pnpm 版本。这些配置共同保证站点构建在可复现的依赖环境下进行。2.3 版本化文档与跨版本源码链接站点维护了多版本文档website/versions.json 声明了1.3、1.2、1.1、1.0、0.11五个历史版本对应的快照位于website/versioned_docs/侧边栏分别定义在website/versioned_sidebars/下的各版本 JSON 中。一个值得注意的细节是源码链接组件 website/src/components/GithubLink.jsxGithubLink通过useActiveVersion()获取当前读者所在文档版本再结合站点配置中的githubLinkVersionToBaseUrl映射把to属性拼接为该版本对应的代码仓库路径。也就是说当读者浏览 1.2 版本文档时文中对源码的链接自动指向 1.2 分支的对应文件而不是最新代码——本文关联文档 website/docs/development/documentation.md 中对NEWS.md、CONTRIBUTING.md的引用正是通过该组件渲染的。三、小结两条流水线如何协同Hydra 的文档与发布流水线可以概括为变更期每次非平凡的 PR 附带一个或多个news/编号.类别片段类别必须落在 towncrier 声明的七种扩展名之内发布期release 工具驱动 towncrier 按news/_template.rst模板将片段聚合渲染进 NEWS.md版本标题与 issue 链接自动生成展示期Docusaurus 站点在pnpm start/pnpm build前先生成 Landscape 数据站点变更合入 main 后经 NetlifyNode 24、frozen lockfile自动部署多版本文档与跨版本源码链接由versions.json与GithubLink组件共同支撑。对贡献者而言最重要的实操要点只有两条在正确位置核心或插件的news/目录按正确类别创建片段文件并保持片段文本简洁、面向用户站点侧则只需在website目录内使用 corepack 管理的 pnpm 命令完成开发、构建与验证。【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hydra 文档体系实战：用 towncrier 管理 NEWS.md，用 Docusaurus 构建官方站点
Hydra 文档体系实战用 towncrier 管理 NEWS.md用 Docusaurus 构建官方站点【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydraHydra 仓库的文档基础设施由两部分组成一是基于 towncrier 的 NEWS.md 变更日志流水线贡献者只需提交小型 news fragment 文件发布时自动聚合渲染二是基于 Docusaurus 3 pnpm 的官方文档站点支持本地开发、静态构建与自动部署。读完本文你将掌握 Hydra 中新闻片段的分类规则与放置约定、pnpm 工作区对依赖发布的稳定性策略以及站点从pnpm start到 Netlify 部署的完整链路。一、NEWS.md 由 towncrier 统一管理Hydra 的 NEWS.md 并不由开发者手工维护而是交给 towncrier 中定义了完整的片段规范文件名以对应的 issue 或 PR 编号命名扩展名为类别名例如news/1234.bugfix放置位置Hydra 核心变更放根目录 news/插件变更放对应插件的news/目录例如plugins/hydra_optuna_sweeper/news/1234.feature多类别变更一个 PR 可以同时包含多个片段。比如既新增功能又弃用旧接口就同时创建news/1234.feature和news/1234.api_change如果一次变更涉及多个 issue 编号可以为每个编号各建一个内容相同的片段发布工具在渲染时会去重文风要求片段应简洁、面向用户使用句子式大小写sentence case、不超过 80 字符、祈使语气且要能补全句子 This change will ...片段文本中不需要写 issue/PR 编号引用链接由发布工具自动追加。当前仓库根目录的 news/ 目录就是这套机制的现场目录下有大量形如2928.bugfix、3206.feature、3287.api_change的待发布片段等待下一次 release 聚合进 NEWS.md。1.1 towncrier 配置项解读towncrier 的全部配置位于 pyproject.toml 的[tool.towncrier]段[tool.towncrier] package hydra package_dir filename NEWS.md directory news/ title_format {version} ({project_date}) template news/_template.rst issue_format #{issue} start_string !-- TOWNCRIER --\n各字段的实际含义配置值作用filenameNEWS.md生成的变更日志目标文件directorynews/收集新闻片段的目录title_format{version} ({project_date})每个版本标题的格式即1.3.2 (2023-02-22)这样的版本号 (日期)形式templatenews/_template.rst渲染所用的 Jinja2 模板见下文issue_format#{issue}片段后自动附加的 issue 链接格式start_string!-- TOWNCRIER --NEWS.md 中的标记注释towncrier 只在该标记之前插入新版本记录同一配置段还通过[[tool.towncrier.type]]声明了受支持的片段类别与 CONTRIBUTING.md 的约定一一对应扩展名渲染标题说明featureFeatures新功能api_changeAPI Change (Renames, deprecations and removals)API 变更、重命名、弃用与移除bugfixBug Fixes缺陷修复pluginPlugins插件相关变更configConfiguration structure changes配置结构变化docsImproved Documentation文档改进maintenanceMaintenance Changes可维护性改进1.2 渲染模板与最终效果渲染逻辑由 news/_template.rst 控制。它是一个 Jinja2 模板按 section 迭代对每个类别输出### {{ definitions[category][name] }}小节再把该类别下所有片段逐条以列表项输出对非plugin/process类别条目后会追加排序后的 issue 引用。若某类别为空则输出 No significant changes.。打开 NEWS.md 可以看到渲染后的真实结果例如1.3.2 (2023-02-22)版本下按 Features、Maintenance Changes 分节每条变更都带有指向对应 issue 的链接——这正是issue_format与模板共同作用的产物。从源码结构看仓库的tools/release/目录提供了 release 脚本与配套测试tools/release/release.py、tools/release/test_release.py发布流程会在打 tag 时驱动 towncrier 完成片段聚合与清理。二、网站搭建Docusaurus 3 pnpmHydra 的官方文档站点位于 website/ 目录基于 Docusaurus 3 构建website/README.md 中说明的版本要求为 Node.js 24 与 Python 3.10Python 用于在站点命令执行前运行确定性的 Hydra Landscape 生成器。2.1 安装与本地开发所有命令都在website目录下执行通过 corepack 统一 pnpm 版本$ corepack pnpm install安装完成后启动本地开发服务器$ corepack pnpm start从 website/package.json 的 scripts 定义可以看到start实际是start: node scripts/run-landscape-generator.mjs docusaurus start --port 9134也就是说pnpm start会先运行 Landscape 数据生成脚本再启动 Docusaurus 开发服务器固定端口 9134并打开浏览器窗口大多数修改无需重启即可热更新生效。pnpm build同样会先生成 Landscape 数据再把静态内容输出到build/目录可交由任意静态托管服务部署新增页面放入docs/后可经http://localhost:9134/docs/page_name本地访问。部署则全自动完成网站变更合入 main 分支后自动发布构建环境由 netlify.toml 固定为NODE_VERSION 24并使用--frozen-lockfile安装。2.2 pnpm 工作区的依赖稳定性策略文档中提到pnpm 被配置为在依赖更新时避免解析最近 10 天内发布的 npm 包版本这一策略的具体实现就在 website/pnpm-workspace.yamlminimumReleaseAge: 14400即 14400 分钟10 天包版本发布未满 10 天不会被解析选中以此规避刚发布即出现问题的包minimumReleaseAgeExclude为一批经过审查的包如js-yaml4.3.1、qs6.15.2豁免该限制overrides对 Babel、webpack、express、dompurify 等供应链关键包做版本锁定allowBuilds/strictDepBuilds禁用core-js、core-js-pure的构建脚本并启用严格依赖构建收紧安装期执行面patchedDependencies将image-size2.0.2指向patches/image-size2.0.2.patch以本地补丁修复该包的安全公告同时在auditConfig.ignoreGhsas中忽略对应编号并注释说明原因。package.json还声明了packageManager: pnpm11.21.0与engines: {node: 24}配合 corepack 保证团队成员与 CI 使用同一 pnpm 版本。这些配置共同保证站点构建在可复现的依赖环境下进行。2.3 版本化文档与跨版本源码链接站点维护了多版本文档website/versions.json 声明了1.3、1.2、1.1、1.0、0.11五个历史版本对应的快照位于website/versioned_docs/侧边栏分别定义在website/versioned_sidebars/下的各版本 JSON 中。一个值得注意的细节是源码链接组件 website/src/components/GithubLink.jsxGithubLink通过useActiveVersion()获取当前读者所在文档版本再结合站点配置中的githubLinkVersionToBaseUrl映射把to属性拼接为该版本对应的代码仓库路径。也就是说当读者浏览 1.2 版本文档时文中对源码的链接自动指向 1.2 分支的对应文件而不是最新代码——本文关联文档 website/docs/development/documentation.md 中对NEWS.md、CONTRIBUTING.md的引用正是通过该组件渲染的。三、小结两条流水线如何协同Hydra 的文档与发布流水线可以概括为变更期每次非平凡的 PR 附带一个或多个news/编号.类别片段类别必须落在 towncrier 声明的七种扩展名之内发布期release 工具驱动 towncrier 按news/_template.rst模板将片段聚合渲染进 NEWS.md版本标题与 issue 链接自动生成展示期Docusaurus 站点在pnpm start/pnpm build前先生成 Landscape 数据站点变更合入 main 后经 NetlifyNode 24、frozen lockfile自动部署多版本文档与跨版本源码链接由versions.json与GithubLink组件共同支撑。对贡献者而言最重要的实操要点只有两条在正确位置核心或插件的news/目录按正确类别创建片段文件并保持片段文本简洁、面向用户站点侧则只需在website目录内使用 corepack 管理的 pnpm 命令完成开发、构建与验证。【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考