NixOS/Nix 项目文档贡献指南与技术规范

NixOS/Nix 项目文档贡献指南与技术规范

nix Nix, the purely functional package manager 项目地址: https://gitcode.com/gh_mirrors/ni/nix

前言

作为Nix生态系统的核心项目，NixOS/Nix的文档质量直接影响着用户的使用体验。本文将系统性地介绍如何为该项目贡献文档，包括构建方法、风格指南和技术规范，旨在帮助开发者编写出清晰、一致且易于维护的文档。

文档构建指南

完整构建手册

对于需要完整构建文档的场景，可以使用以下两种等效命令：

nix-build -E '(import ./.).packages.${builtins.currentSystem}.nix.doc'

或更简洁的：

nix build .#nix-manual

构建完成后，文档将生成在./result/share/doc/nix/manual/index.html路径下。

增量开发构建

在日常文档开发中，为提高效率推荐使用增量构建方式：

1. 首先进入开发环境
2. 执行以下命令实现快速构建并自动打开浏览器：

make manual-html-open -j $NIX_BUILD_CORES

清理与重建

当修改了文档构建系统的Makefile后，需要清理生成的文件以确保变更生效：

rm $(git ls-files doc/manual/ -o | grep -F '.md') && \
rmdir doc/manual/source/command-ref/new-cli && \
make manual-html -j $NIX_BUILD_CORES

文档风格规范

核心原则

Nix文档作为参考文档(Reference Documentation)，应当遵循以下核心原则：

1. 准确性：内容必须与代码实现严格一致
2. 一致性：术语和风格保持统一
3. 完整性：覆盖所有关键功能和场景
4. 可检索性：便于用户快速定位所需信息

语言规范

1. 简明清晰：

   • 采用简洁的语句结构
   • 避免冗长复杂的句式
   • 每个句子独立成行（便于版本控制）

2. 客观描述：

   • 仅陈述事实，不做主观评价
   • 不确定的内容应通过代码验证

3. 示例规范：

   • 提供完整且最小化的示例
   • 确保示例可直接运行并产生预期结果
   • 在文本中解释示例的功能和关键点

4. 语言选择：

   • 使用英式英语(British English)
   • 保持拼写和术语的一致性

链接与锚点

1. 术语链接：

   • 为所有Nix专有概念添加内部链接
   • 为可能产生歧义的外部术语添加解释链接

2. URL稳定性：

   • 避免破坏已有文档URL
   • 必要的URL变更需设置重定向

3. 终端友好：

   • 链接文本应包含可搜索的关键词
   • 考虑man page等不支持超链接的场景

Markdown编写规范

1. 基础格式：

   • 每行一个句子
   • 使用参考式链接（但不宜过多）

2. 特殊区块：

   • 注意(Note)区块：

     > **Note**
     >
     > 这里是注意事项
     

   • 示例(Example)区块：

     > **Example**
     >
     ```console
     $ nix --version
     ```
     

   • 语法(Syntax)区块（使用EBNF notation）：

     > **Syntax**
     >
     > *attribute-set* = `{` [ *attribute-name* `=` *expression* `;` ... ] `}`
     

3. 路径处理：

   • 在可复用代码片段中使用@docroot@作为基础路径
   • 常规Markdown文件应使用相对路径

API文档构建

内部API文档

构建命令：

nix build .#hydraJobs.internal-api-docs
xdg-open ./result/share/doc/nix/internal-api/html/index.html

或在开发环境中：

configurePhase
ninja src/internal-api-docs/html
xdg-open src/internal-api-docs/html/index.html

C API文档

（注意：C API目前尚未稳定）

构建命令：

nix build .#hydraJobs.external-api-docs
xdg-open ./result/share/doc/nix/external-api/html/index.html

或在开发环境中：

configurePhase
ninja src/external-api-docs/html
xdg-open src/external-api-docs/html/index.html

最佳实践建议

1. 渐进式改进：

   • 避免大规模重构，优先解决具体问题
   • 程序化变更需包含验证机制

2. 审查友好：

   • 保持变更范围明确
   • 复杂修改应分解为多个小提交

3. 自动化检查：

   • 利用现有工具检查链接有效性
   • 注意处理@docroot@相关的构建警告

通过遵循这些规范，开发者可以为Nix项目贡献出高质量的文档，帮助用户更好地理解和使用这一强大的工具链。

nix Nix, the purely functional package manager 项目地址: https://gitcode.com/gh_mirrors/ni/nix