企业官网建设流程全解析

• 音视频
• 视频处理
• 图形学
• 桌面应用

导读

本文基于 Natron 开源仓库的官方写作指南（tutorials-writedoc.rst），系统讲解 Natron 文档体系的组织结构、编写规范、本地构建验证流程，以及插件文档（主文档 + Markdown 补充文档）的生成机制与提交方法。读完本文，你将掌握：如何在Documentation/source/guide目录下编辑用户指南、如何用 Sphinx 或 pandoc 本地预览修改、如何通过插件源码中的kPluginDescription等宏更新插件参数说明，以及如何按官方流程把文档改动合并进 Natron 主仓库。

一、Natron 文档体系概述

Natron 的文档源文件全部位于 Documentation/source 目录，采用Sphinx构建、reStructuredText（reST）作为源文件格式。整个文档体系由四个主要部分构成，可从 Documentation/source/index.rst 的根toctree看到：

• 用户指南（user-guide）：位于Documentation/source/guide，包含入门、环境、节点使用、合成专题与教程等全部面向最终用户的内容；
• 参考指南（reference-guide）：对应 _group.rst，由"偏好设置（_prefs.rst）、环境变量（_environment.rst）、以及按节点组（Image、Draw、Time、Channel、Color、Filter、Keyer、Merge、Transform、Views、Other、GMIC、Extra 等）组织的节点文档"组成；
• 开发者指南（developers-guide）：位于Documentation/source/devel，讲解 Python 脚本与命令行渲染器（NatronRenderer）；
• 维护者指南（maintainers-guide）：位于Documentation/source/maintainers，面向希望参与 Natron C++ 源码的开发者。

文档采用CC-BY-SA 4.0许可（见 index.rst 与 conf.py 的版权声明），由志愿者维护，并且也发布在线上（Read the Docs 版本 rb-2.6，可下载 PDF、HTML zip、ePub 等格式）。

关键事实：从 conf.py 可以看出，当前分支对应2.6.0版本（release = version_26），文档同时记录了 2.1～3.0 多个历史版本号（version_21 = '2.1.10'至version_30 = '3.0.0'），并指定了 HTML 主题sphinx_rtd_theme、Logo_static/logo.png、自定义样式theme_overrides.css，以及 LaTeX/PDF 输出配置（含Gui/Resources/Images/natronIcon.pdf标题页 Logo）。

二、编写用户指南：编辑与新增 reST 文档

2.1 源文件位置与编辑方式

绝大多数文档贡献者关注的是用户指南。其源文件位于Documentation/source/guide目录，命名具有明显的组织规律：

• getstarted-*：入门与安装（Linux / Mac / Windows）、环境（界面、节点图、属性面板、查看器、时间线、撤销重做、预置等）、FAQ 与故障排查；
• thenodes-*：各类节点使用手册（Roto、Merge、Read/Write、Checkboard、ColorWheel、各类 Draw 节点等）；
• compositing-*：合成专题（通道、色彩、键控、合并、变换、跟踪、RotoPaint、立体、时间线、渲染、工程设置等）；
• tutorials-*：完整教程，如 tutorials-hsvtool.rst、tutorials-ffmpeg.rst、tutorials-svgworkflow.rst 等。

编辑已有文档只需用普通文本编辑器（plain text-editor）打开对应.rst文件直接修改即可；新增文档则建议参考现有文件的结构与命名规范，并将其登记进 guide/index.rst 的目录树。

2.2 必须遵守的"只读"文件清单

以下文件由程序自动生成，严禁手工编辑（这一点在官方指南中以note明确标出，也在文件头部写有警告）：

• _group.rst及所有以_group开头的文件（_groupImage.rst、_groupDraw.rst、_groupColor.rst等，见 _group.rst 头部 "Do not edit this file! It is generated automatically by Natron itself."）；
• _prefs.rst（偏好设置文档，同样在 _prefs.rst 头部有自动生成警告）；
• Documentation/source/plugins 目录下的每个插件文档（由 Natron 运行时导出、经 pandoc 转换而来）。

这些自动生成文件的真正"源头"在插件源码与 Natron 自身的元数据中，下一章将详细说明。

2.3 用 pandoc 从 Word 文档起步（可选路径）

如果你习惯用 LibreOffice 或 MS Word 编辑，官方指南给出的折中方案是：

1. 在 Word 中保持文档简洁：用样式标记章节标题，不要过度排版；
2. 用 pandoc 转换出第一个可用的 reST 版本：

pandoc your_document.docx -t rst -o output_doc.rst

转换产物通常还需要少量手工润色，但作为起点已经足够。此外，交互式预览 reST 还可以借助 RstPad 这类专门编辑器（支持 Mac 与 Windows）。

三、本地构建与预览：Sphinx 实战

3.1 安装依赖

官方指南给出的安装方式（按平台）：

• macOS（MacPorts）：sudo port install py27-sphinx py27-sphinx_rtd_theme
• macOS（HomeBrew）：brew install sphinx-doc; /usr/local/opt/sphinx-doc/libexec/bin/pip3 install sphinx_rtd_theme
• Linux：pip install sphinx sphinx_rtd_theme
• Windows：参照 Sphinx 官方安装文档安装 Python 与 Sphinx

当前仓库在 Documentation/source/requirements.txt 中锁定了依赖版本，可作为现代环境（Python 3 + pip）下更精确的参考：

docutils<0.18 sphinx-rtd-theme==1.0.0 sphinx-copybutton==0.4.0

即在较新环境下推荐使用pip install -r Documentation/source/requirements.txt安装，再按下一节命令构建。

3.2 构建 HTML 文档

进入Documentation目录，执行：

sphinx-build -b html source html

生成结果位于Documentation/html目录，用浏览器打开Documentation/html/index.html即可预览自己的修改。构建行为受 Documentation/source/conf.py 控制：源文件后缀为.rst（source_suffix = '.rst'）、主文档为index（master_doc = 'index'）、HTML 主题为sphinx_rtd_theme，并加载_static/theme_overrides.css覆盖样式。

3.3 为什么文档能同时在多个渠道输出

Sphinx 的配置文件同时定义了 HTML、LaTeX（PDF）、man、texinfo 四类输出（conf.py 的html_*、latex_documents、man_pages、texinfo_documents各段），这正是线上文档站可以同时提供 HTML 在线阅读与 PDF/ePub 下载的原因。

四、插件文档：源码即文档

插件文档是 Natron 文档体系中"自动化程度最高"的部分，分为两大部分。

4.1 主文档：来自插件 C++ 源码

每个插件的主文档（短描述 + 每个参数的说明）直接写在插件的 C++ 源文件里，核心机制是一组#define宏：

• kPluginDescription：插件描述。它在 Natron 中悬停插件属性面板的?按钮时显示，也是生成的 HTML 文档中的 Description 部分；换行用\n表示。
• 参数 hint 宏（如 Checkerboard 插件中的kParamBoxSizeHint、kParamColor0Hint等）：描述每个参数，鼠标悬停参数时显示，并进入在线 HTML 文档。

以 Checkerboard 插件为例的修改流程：

1. 复刻插件仓库（openfx-misc 等）；
2. 用文本编辑器打开Checkerboard/Checkerboard.cpp；
3. 定位到#define kPluginDescription行修改描述文本；
4. 重新构建插件并加载到 Natron，点击属性面板的?按钮验证改动。

从 Natron 侧看，插件文档是在运行时由Node::makeDocumentation(bool genHTML)（实现见 Engine/NodeDocumentation.cpp）收集生成的：它读取插件的getPluginDescription()、isPluginDescriptionInMarkdown()、输入标签/提示（getInputLabel、getInputHint）、输入是否可选（isInputOptional）以及图标路径（getIconFilePath）等元数据（Engine/NodeDocumentation.cpp），组装成文档结构。PyPlug（Python 插件）则由pyPlugID、pyPlugLabel、pyPlugDesc、pyPlugIconFilePath等字段驱动（Engine/NodeDocumentation.cpp）。节点对象上的接口声明见 Engine/Node.h。

4.2 补充文档：插件包内的 Markdown 文件

主文档之外，每个插件还可以附带一段额外文档（extra documentation）：一个放在插件包Contents/Resources/目录下的 Markdown 文件，命名为pluginId.md（pluginId为完整插件标识符，例如net.sf.openfx.MergePlugin），与插件图标文件同目录。这段额外文档会被插入到生成文档的Description段之后、Inputs段之前。

Natron 侧的加载逻辑印证了这一点：makeDocumentation()会把插件图标路径中的.png替换为.md（pluginMD.replace(".png", ".md")），如果该文件存在则读取其全部内容作为extraMarkdown插入文档（Engine/NodeDocumentation.cpp，此处路径以仓库根目录为基准为 Engine/NodeDocumentation.cpp）。

4.3 为插件启用 Markdown 格式

插件描述与参数可选地支持 Markdown 语法，以获得更精细的排版控制。启用方式是在插件的describe函数中调用：

desc.setPluginDescription(kPluginDescriptionMarkdown, true);

官方指南建议参考 Shadertoy 插件的实现来理解这一机制。如果对这套流程不熟悉，也可以直接联系插件仓库维护者代为启用。对应的运行时检测即为上文的isPluginDescriptionInMarkdown()（Engine/NodeDocumentation.cpp）。

4.4 静态文档的自动生成链路（源码级补充）

Documentation/source/plugins下的所有.rst文件都不是手写的。完整的自动化链路由 tools/genStaticDocs.sh 实现，流程如下：

1. 调用已构建好的NatronRenderer可执行文件，通过--export-docs参数配合一个临时工程（dummy.ntp）把每个插件的文档导出为 Markdown（$NATRON_BIN ... --export-docs "$TMP_FOLDER" "$TMP_FOLDER/dummy.ntp"，见 tools/genStaticDocs.sh）；
2. 用pandoc 2.3.1（脚本对 ≥2.4 版本会报错并中止，因为无法强制生成 grid tables，见 tools/genStaticDocs.sh）把 Markdown 转换为带grid_tables的 reST；
3. 用sed做一系列后处理：为每个插件文件头插入.. _pluginID:锚点、修正多行表格单元标记、把CONTROLSTABLEPROPS占位符替换为tabularcolumns/cssclass:: longtable属性、把自定义的 html/rst 交叉链接转换成:ref:形式（tools/genStaticDocs.sh）；
4. 最后把生成的.rst与插件图标.png拷贝回Documentation/source/plugins目录（tools/genStaticDocs.sh）。

这解释了为什么插件.rst文件头部都带有 "Do not edit this file! It is generated automatically by Natron itself." 的raw:: html注释——例如 Documentation/source/plugins/eu.cimg.EdgeDetect.rst。此类生成文件还保留了|pluginIcon|占位符与规范化的 "Description / Inputs / Controls" 三段式表格结构（参数名、脚本名、类型、默认值、功能说明），例如 EdgeDetect 的 Controls 表格展示了filter（Choice）、multiChannel（Choice）、blurSize（Double）、nms（Boolean）等参数，这正是kParamXXXHint宏与运行时文档导出的最终呈现。

五、提交文档贡献：官方流程与渠道

5.1 标准提交流程

官方指南推荐的标准流程为：

1. 用 GitHub 账号 fork 主仓库https://github.com/NatronGitHub/Natron；
2. 在 fork 上基于RB-2.4分支创建新分支（不要用 master），按内容命名，例如准备写键控（keying）相关文档时可命名为documentation-keying；
3. 二选一提交改动：
   • 本地方式：clone 仓库到本地，编辑并新增文件、本地 commit（可用 GitHub Desktop 简化操作）后 push；
   • 在线方式：直接在 GitHub 网页编辑。官方指南以 tutorials-hsvtool.rst 为例，说明可以点文件右上角的铅笔图标进入可编辑文本视图，并通过顶部的 Preview 标签页预览渲染效果；
4. 从你的分支向主仓库的RB-2.4分支提交pull request，写明准确的 PR 描述，并遵循 Contributor Covenant Code of Conduct（与 Natron 及插件所有贡献行为一致）。维护者可能直接接受，也可能要求少量修改后合并。

说明：当前仓库的 conf.py 显示文档分支对应 2.6.0 版本，且记录"当前维护版本需合并进 master 分支"（the list of currently maintained versions (those that have to be merged into the master branch)），因此提交目标分支请以当下维护策略为准，官方指南原文写的是基于 RB-2.4 分支。

5.2 不合规格式时的替代渠道

如果你写了一篇格式不错的文档（任意标准格式均可），但不太熟悉上述 Git 流程，可以在提交前先征求协助：

• 到 Natron 论坛发帖求助（官方指南指向 discuss.pixls.us 的 Natron 分区）；
• 或直接提交 GitHub issue，并把文档作为附件附在消息中。

5.3 插件文档的独立提交流程

插件文档不经过 Natron 主仓库，而是提交到对应的插件仓库的master分支，按插件归属分为四类：

• openfx-misc（通用/滤镜类，Checkerboard、Shadertoy 等属于此类）；
• openfx-io（读写类）；
• openfx-arena；
• openfx-gmic（G'MIC 系列）。

流程同样是 fork → 建分支 → 改源码宏或 Markdown → pull request 到该插件仓库的master分支。遇到困难同样可以走论坛/issue 渠道求助。

六、写作质量自查清单

结合官方指南要点与上文自动化机制，提交前建议逐项核对：

1. 不碰自动生成文件：_group*.rst、_prefs.rst、Documentation/source/plugins/*.rst均由程序生成，改动会被下一次genStaticDocs.sh覆盖，应改其源头（插件源码宏 / 插件包内pluginId.md/ 偏好设置源码）；
2. 源文件格式正确：.rst源文件遵循 reStructuredText 语法；Word/LibreOffice 起草的内容先经pandoc -t rst转换再润色；
3. 本地验证：cd Documentation && sphinx-build -b html source html，打开Documentation/html/index.html确认渲染无误；
4. 构建环境匹配：Sphinx 依赖以 Documentation/source/requirements.txt 为准；生成静态插件文档需使用支持--export-docs的 Natron 构建与 pandoc 2.3.1（见 tools/genStaticDocs.sh）；
5. 分支与合规：按官方流程创建命名清晰的分支、提交准确的 PR 描述、遵守 Contributor Covenant Code of Conduct。

七、总结

Natron 的文档体系是一套"人写 + 机器生成"结合的混合结构：用户指南由贡献者在Documentation/source/guide中用 reST 编写、经 Sphinx 构建；偏好设置、节点分组与插件文档则分别由 Natron 运行时与genStaticDocs.sh自动生成，插件作者只需维护 C++ 源码中的kPluginDescription/参数 hint 宏或插件包内的pluginId.md补充文档。理解这条链路后，无论是修改用户指南、更新插件参数说明，还是参与静态文档的再生成，都能快速定位正确的改动位置，并通过sphinx-build在本地完成验证。

• 音视频
• 视频处理
• 图形学
• 桌面应用