bottom 文档贡献指南帮助菜单、README 与 MkDocs 扩展文档的完整维护流程【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom本篇指南以 bottom跨平台终端图形化进程/系统监控工具仓库中的 docs/content/contribution/documentation.md 为核心系统梳理该项目文档维护的时机、范围、流程与工具链。读者将掌握何时需要补文档、哪些页面归谁管、如何本地启动 MkDocs 校验改动以及如何将修改通过 Pull Request 合入主分支并了解项目对 AI 生成文档的明确限制。什么时候需要更新文档bottom 项目对文档的定位是“与代码变更同步交付”文档不是发布前的可选附加项而是功能合入的一部分。文档团队或贡献者本人应在以下场景主动触发文档更新新增功能、修复 Bug 或引入破坏性变更breaking change时必须在合适的位置记录典型落点是README.md、CHANGELOG.md及扩展文档等出现新的安装方式时官方始终欢迎并期待将其写入文档例如通过包管理器、预编译二进制或源码构建等渠道的新增内容。这一原则与仓库的实际结构相印证CHANGELOG.md记录了每个版本的变更明细README.md承担安装与快速上手的入口职责而 docs/content/ 目录下的扩展文档则承载更细致的用法与配置说明。哪些页面需要文档四类文档落点bottom 的文档分散在四个不同位置贡献者需要先判断自己的改动属于哪一类再选择对应的编辑方式文档落点仓库路径作用主 READMEREADME.md项目门面安装方法、特性概览、快速使用应用内帮助菜单src/constants.rs运行btm后按?打开的交互式帮助扩展文档docs/content/index.md当前正在阅读的这套站点承载深度的用法、配置与贡献说明变更日志CHANGELOG.md按版本记录新增、修复与破坏性变更从 docs/mkdocs.yml 的nav配置可以看到扩展文档被组织为 Support、UsageWidgets 用法、ConfigurationConfig File 与命令行选项、Contribution贡献、Troubleshooting 五大板块其中 Contribution 板块就包含documentation.md所在的 contribution/ 目录说明文档本身的维护也走“文档化”流程。帮助菜单的文档藏在源码里一个容易被忽略的落点是应用内帮助菜单。它并非由 Markdown 维护而是直接以字符串数组形式内嵌在 src/constants.rs 中。从源码结构看该文件定义了 10 个帮助分区HELP_CONTENTS_TEXT帮助菜单封面提示“按数字键跳转到对应分区”并说明可用Ctrl-f或/在帮助文本内搜索关键词GENERAL_HELP_TEXT全局键位退出、冻结刷新、窗口移动、缩放图表等 24 条CPU_HELP_TEXT、PROCESS_HELP_TEXT、SEARCH_HELP_TEXT、SORT_HELP_TEXT、TEMP_HELP_WIDGET、DISK_HELP_WIDGET、BATTERY_HELP_TEXT、BASIC_MEM_HELP_TEXT分别对应各 Widget 的键位与搜索语法说明最终通过pub(crate) const HELP_TEXT: [[str]; HELP_SECTIONS]汇总为统一数组src/constants.rs。因此修改帮助菜单时不要去改某个 Markdown 文件而是参照该文件中既有条目的格式在对应常量数组中追加或调整字符串。例如SEARCH_HELP_TEXT中完整列出了进程搜索的类型pid、cpu、mem、read、write等、比较运算符、!、、、、与单位B、KB、MB、KiB…新增搜索能力时必须同步维护这段文案否则帮助菜单会与实际行为脱节。如何新增或更新文档完整操作流程第一步Fork 仓库所有文档改动都在 Fork 出的副本中进行之后通过 Pull Request 合入main分支。这与其他代码贡献的流程一致详见 docs/content/contribution/issues-and-pull-requests.md。第二步按文档落点选择编辑方式README.md或CHANGELOG.md直接用任意编辑器遵循文件内既有格式即可。需要注意两点惯例CHANGELOG.md的维护通常由 maintainer 负责贡献者一般不需要自行改写变更日志应遵循Keep a Changelog格式规范并链接到相关的 PR 或 issue便于追溯。应用内帮助菜单参照 src/constants.rs 中现有帮助文本的生成方式在对应常量数组中修改。扩展文档这是流程最重的部分。本地校验需要以下工具链Python 3.11 及以上文档中说明更早或更新的版本通常也没问题MkDocsMaterial for MkDocs 主题mdx_truly_sane_lists列表解析扩展用于修复 MkDocs 列表渲染的已知问题可选Mike版本化文档部署工具仓库实际上已在依赖中固定了它见下文。第三步本地启动扩展文档站点仓库为扩展文档提供了一键脚本 docs/serve.sh。在仓库根目录执行cd docs/ ./serve.sh脚本的行为见 docs/serve.sh若.venv不存在则用python -m venv .venv创建虚拟环境安装 docs/requirements.txt 中的依赖然后启动mkdocs serve若虚拟环境已存在则直接激活并升级依赖后启动。默认使用python命令也可通过第一个参数指定例如./serve.sh python3。启动后浏览器打开本地服务地址即可预览文档且会随着文件保存实时刷新适合边改边校验。如果想手动复现同样的环境可以参考 docs/README.md 给出的等价步骤cd docs/ python -m venv venv source venv/bin/activate pip install -r requirements.txt venv/bin/mkdocs serve此外仓库还提供 docs/mike.sh用于本地以 Mike 方式预览带版本号的站点注意脚本注释提醒这种方式不反映未提交的本地改动因为它读取的是已部署的版本数据而非工作区文件。依赖与构建配置的细节从 docs/requirements.txt 可以看到当前固定的构建依赖文件顶部还留有一条 TODO 注释提到 mkdocs-material 已进入维护模式、未来可能需要迁移——贡献者若发现构建行为异常这条注释是重要的背景信息mkdocs 1.6.1 mkdocs-material 9.7.6 mdx_truly_sane_lists 1.3 mike 2.1.4 mkdocs-git-revision-date-localized-plugin 1.4.5 mkdocs-redirects 1.2.2而 docs/mkdocs.yml 定义了站点全貌docs_dir指向content/使用 Material 主题并启用即时导航、搜索高亮、代码高亮、标签页等特性插件侧启用了tags、search、mikecanonical_version: stable、git-revision-date-localized、privacy与redirects其中把nightly-release.md重定向到 releases 页面还有两个构建钩子 docs/hooks/nightly_redirect.py 与 docs/hooks/nightly_banner.py用于在 nightly 版本站点上显示横幅并做跳转。修改文档时若涉及导航结构或版本相关页面这些配置都值得留意。第四步提交 Pull Request文档改动完成后按 docs/content/contribution/issues-and-pull-requests.md 中的流程提交 PR。该文档强调PR 应填写模板与检查清单交由 maintainer 评审CIclippy lint、rustfmt 检查与基础测试通过后合入且项目通常采用 squash 合并以保持提交历史整洁。扩展文档的版本化部署维护者视角对普通贡献者而言本地mkdocs serve已足够若你承担维护职责并需要发布文档docs/README.md 记录了基于 Mike 的部署流程文档一般由 CI 自动执行但也可手动操作Nightly 文档cd docs mike deploy nightly --push稳定版文档先把上一版稳定版重命名存档再部署新版本并打上stable别名与(stable)标识cd docs # 将之前的 stable 版本重命名为其真实版本号 mike retitle --push stable $OLD_STABLE_VERSION # 将新版本部署为最新的 stable 版本 mike deploy --push --update-aliases $RELEASE_VERSION stable # 在版本标题后追加 (stable) 字符串 mike retitle --push $RELEASE_VERSION $RELEASE_VERSION (stable)这套流程与 schema/ 下按v0.9、v0.10、v0.14.7、nightly分版本维护配置 JSON Schema 的做法一致体现了 bottom 文档“版本化”的整体设计。AI 政策文档绝不允许由 AI 生成bottom 项目对 AI 参与贡献有非常明确的立场这一点同样约束文档工作。原文档明确指出文档绝不应由 AI 生成——文档的存在意义是“在人与人之间传递信息”。任何不符合该政策的改动都可能被直接关闭或隐藏。具体约束见仓库根目录的 AI_POLICY.md核心条款包括AI 不得完全生成与维护者沟通的评论被认为完全由 AI 生成的评论可能被无通知隐藏提交 issue 时必须用自己的话描述问题且遵循模板纯 AI 驱动的低质量 issue 可能被直接关闭提交 PR 时须用自己的话解释改动、回答维护者问题、自行测试PR 模板与检查清单不得完全由 AI 填写回复维护者时不得直接复制 AI 的回答若确实要引用与 AI 交互的内容必须放入引用块并明确披露同时附上人类撰写的相关性与影响说明且不得粘贴大段文本唯一的例外场景是语言辅助若英语不熟练允许用 AI 润色语法拼写需确保仍反映自己的声音与想法用于翻译时建议用母语写作并把译文放入引用块。因此在提交任何文档相关 PR 之前请先通读 AI_POLICY.md 并逐条自检——即便你的改动本身不是 AI 生成的与维护者的沟通过程同样受该政策约束。小结一次合规的文档贡献的完整链路综合上述内容一次合格的 bottom 文档贡献应依次完成判断变更是否触及 README / 帮助菜单 / 扩展文档 / CHANGELOG 四类落点之一 → Fork 仓库并按对应方式修改帮助菜单改 src/constants.rs 的常量数组扩展文档通过 docs/serve.sh 本地预览→ 遵循 Keep a Changelog 等格式惯例 → 提交填写完整的 Pull Request → 确保与维护者的所有沟通符合 AI_POLICY.md 的人工撰写要求。文档在 bottom 项目中不是孤立的附属品而是与功能、测试、版本化构建MkDocs Mike紧密耦合的正式交付物这也是该项目文档体系能够长期保持清晰可维护的根本原因。【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 bottom 文档贡献指南：帮助菜单、README 与 MkDocs 扩展文档的完整维护流程
bottom 文档贡献指南帮助菜单、README 与 MkDocs 扩展文档的完整维护流程【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom本篇指南以 bottom跨平台终端图形化进程/系统监控工具仓库中的 docs/content/contribution/documentation.md 为核心系统梳理该项目文档维护的时机、范围、流程与工具链。读者将掌握何时需要补文档、哪些页面归谁管、如何本地启动 MkDocs 校验改动以及如何将修改通过 Pull Request 合入主分支并了解项目对 AI 生成文档的明确限制。什么时候需要更新文档bottom 项目对文档的定位是“与代码变更同步交付”文档不是发布前的可选附加项而是功能合入的一部分。文档团队或贡献者本人应在以下场景主动触发文档更新新增功能、修复 Bug 或引入破坏性变更breaking change时必须在合适的位置记录典型落点是README.md、CHANGELOG.md及扩展文档等出现新的安装方式时官方始终欢迎并期待将其写入文档例如通过包管理器、预编译二进制或源码构建等渠道的新增内容。这一原则与仓库的实际结构相印证CHANGELOG.md记录了每个版本的变更明细README.md承担安装与快速上手的入口职责而 docs/content/ 目录下的扩展文档则承载更细致的用法与配置说明。哪些页面需要文档四类文档落点bottom 的文档分散在四个不同位置贡献者需要先判断自己的改动属于哪一类再选择对应的编辑方式文档落点仓库路径作用主 READMEREADME.md项目门面安装方法、特性概览、快速使用应用内帮助菜单src/constants.rs运行btm后按?打开的交互式帮助扩展文档docs/content/index.md当前正在阅读的这套站点承载深度的用法、配置与贡献说明变更日志CHANGELOG.md按版本记录新增、修复与破坏性变更从 docs/mkdocs.yml 的nav配置可以看到扩展文档被组织为 Support、UsageWidgets 用法、ConfigurationConfig File 与命令行选项、Contribution贡献、Troubleshooting 五大板块其中 Contribution 板块就包含documentation.md所在的 contribution/ 目录说明文档本身的维护也走“文档化”流程。帮助菜单的文档藏在源码里一个容易被忽略的落点是应用内帮助菜单。它并非由 Markdown 维护而是直接以字符串数组形式内嵌在 src/constants.rs 中。从源码结构看该文件定义了 10 个帮助分区HELP_CONTENTS_TEXT帮助菜单封面提示“按数字键跳转到对应分区”并说明可用Ctrl-f或/在帮助文本内搜索关键词GENERAL_HELP_TEXT全局键位退出、冻结刷新、窗口移动、缩放图表等 24 条CPU_HELP_TEXT、PROCESS_HELP_TEXT、SEARCH_HELP_TEXT、SORT_HELP_TEXT、TEMP_HELP_WIDGET、DISK_HELP_WIDGET、BATTERY_HELP_TEXT、BASIC_MEM_HELP_TEXT分别对应各 Widget 的键位与搜索语法说明最终通过pub(crate) const HELP_TEXT: [[str]; HELP_SECTIONS]汇总为统一数组src/constants.rs。因此修改帮助菜单时不要去改某个 Markdown 文件而是参照该文件中既有条目的格式在对应常量数组中追加或调整字符串。例如SEARCH_HELP_TEXT中完整列出了进程搜索的类型pid、cpu、mem、read、write等、比较运算符、!、、、、与单位B、KB、MB、KiB…新增搜索能力时必须同步维护这段文案否则帮助菜单会与实际行为脱节。如何新增或更新文档完整操作流程第一步Fork 仓库所有文档改动都在 Fork 出的副本中进行之后通过 Pull Request 合入main分支。这与其他代码贡献的流程一致详见 docs/content/contribution/issues-and-pull-requests.md。第二步按文档落点选择编辑方式README.md或CHANGELOG.md直接用任意编辑器遵循文件内既有格式即可。需要注意两点惯例CHANGELOG.md的维护通常由 maintainer 负责贡献者一般不需要自行改写变更日志应遵循Keep a Changelog格式规范并链接到相关的 PR 或 issue便于追溯。应用内帮助菜单参照 src/constants.rs 中现有帮助文本的生成方式在对应常量数组中修改。扩展文档这是流程最重的部分。本地校验需要以下工具链Python 3.11 及以上文档中说明更早或更新的版本通常也没问题MkDocsMaterial for MkDocs 主题mdx_truly_sane_lists列表解析扩展用于修复 MkDocs 列表渲染的已知问题可选Mike版本化文档部署工具仓库实际上已在依赖中固定了它见下文。第三步本地启动扩展文档站点仓库为扩展文档提供了一键脚本 docs/serve.sh。在仓库根目录执行cd docs/ ./serve.sh脚本的行为见 docs/serve.sh若.venv不存在则用python -m venv .venv创建虚拟环境安装 docs/requirements.txt 中的依赖然后启动mkdocs serve若虚拟环境已存在则直接激活并升级依赖后启动。默认使用python命令也可通过第一个参数指定例如./serve.sh python3。启动后浏览器打开本地服务地址即可预览文档且会随着文件保存实时刷新适合边改边校验。如果想手动复现同样的环境可以参考 docs/README.md 给出的等价步骤cd docs/ python -m venv venv source venv/bin/activate pip install -r requirements.txt venv/bin/mkdocs serve此外仓库还提供 docs/mike.sh用于本地以 Mike 方式预览带版本号的站点注意脚本注释提醒这种方式不反映未提交的本地改动因为它读取的是已部署的版本数据而非工作区文件。依赖与构建配置的细节从 docs/requirements.txt 可以看到当前固定的构建依赖文件顶部还留有一条 TODO 注释提到 mkdocs-material 已进入维护模式、未来可能需要迁移——贡献者若发现构建行为异常这条注释是重要的背景信息mkdocs 1.6.1 mkdocs-material 9.7.6 mdx_truly_sane_lists 1.3 mike 2.1.4 mkdocs-git-revision-date-localized-plugin 1.4.5 mkdocs-redirects 1.2.2而 docs/mkdocs.yml 定义了站点全貌docs_dir指向content/使用 Material 主题并启用即时导航、搜索高亮、代码高亮、标签页等特性插件侧启用了tags、search、mikecanonical_version: stable、git-revision-date-localized、privacy与redirects其中把nightly-release.md重定向到 releases 页面还有两个构建钩子 docs/hooks/nightly_redirect.py 与 docs/hooks/nightly_banner.py用于在 nightly 版本站点上显示横幅并做跳转。修改文档时若涉及导航结构或版本相关页面这些配置都值得留意。第四步提交 Pull Request文档改动完成后按 docs/content/contribution/issues-and-pull-requests.md 中的流程提交 PR。该文档强调PR 应填写模板与检查清单交由 maintainer 评审CIclippy lint、rustfmt 检查与基础测试通过后合入且项目通常采用 squash 合并以保持提交历史整洁。扩展文档的版本化部署维护者视角对普通贡献者而言本地mkdocs serve已足够若你承担维护职责并需要发布文档docs/README.md 记录了基于 Mike 的部署流程文档一般由 CI 自动执行但也可手动操作Nightly 文档cd docs mike deploy nightly --push稳定版文档先把上一版稳定版重命名存档再部署新版本并打上stable别名与(stable)标识cd docs # 将之前的 stable 版本重命名为其真实版本号 mike retitle --push stable $OLD_STABLE_VERSION # 将新版本部署为最新的 stable 版本 mike deploy --push --update-aliases $RELEASE_VERSION stable # 在版本标题后追加 (stable) 字符串 mike retitle --push $RELEASE_VERSION $RELEASE_VERSION (stable)这套流程与 schema/ 下按v0.9、v0.10、v0.14.7、nightly分版本维护配置 JSON Schema 的做法一致体现了 bottom 文档“版本化”的整体设计。AI 政策文档绝不允许由 AI 生成bottom 项目对 AI 参与贡献有非常明确的立场这一点同样约束文档工作。原文档明确指出文档绝不应由 AI 生成——文档的存在意义是“在人与人之间传递信息”。任何不符合该政策的改动都可能被直接关闭或隐藏。具体约束见仓库根目录的 AI_POLICY.md核心条款包括AI 不得完全生成与维护者沟通的评论被认为完全由 AI 生成的评论可能被无通知隐藏提交 issue 时必须用自己的话描述问题且遵循模板纯 AI 驱动的低质量 issue 可能被直接关闭提交 PR 时须用自己的话解释改动、回答维护者问题、自行测试PR 模板与检查清单不得完全由 AI 填写回复维护者时不得直接复制 AI 的回答若确实要引用与 AI 交互的内容必须放入引用块并明确披露同时附上人类撰写的相关性与影响说明且不得粘贴大段文本唯一的例外场景是语言辅助若英语不熟练允许用 AI 润色语法拼写需确保仍反映自己的声音与想法用于翻译时建议用母语写作并把译文放入引用块。因此在提交任何文档相关 PR 之前请先通读 AI_POLICY.md 并逐条自检——即便你的改动本身不是 AI 生成的与维护者的沟通过程同样受该政策约束。小结一次合规的文档贡献的完整链路综合上述内容一次合格的 bottom 文档贡献应依次完成判断变更是否触及 README / 帮助菜单 / 扩展文档 / CHANGELOG 四类落点之一 → Fork 仓库并按对应方式修改帮助菜单改 src/constants.rs 的常量数组扩展文档通过 docs/serve.sh 本地预览→ 遵循 Keep a Changelog 等格式惯例 → 提交填写完整的 Pull Request → 确保与维护者的所有沟通符合 AI_POLICY.md 的人工撰写要求。文档在 bottom 项目中不是孤立的附属品而是与功能、测试、版本化构建MkDocs Mike紧密耦合的正式交付物这也是该项目文档体系能够长期保持清晰可维护的根本原因。【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考