SQLFluff 文档贡献指南从 Docstring 到 Sphinx 自动生成文档的完整实践【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluffSQLFluff 的官方文档由两部分构成嵌入在函数与模块docstring中的开发向文档以及由 Sphinx 构建、托管在docs.sqlfluff.com的独立文档。本文以 docs/source/guides/contributing/docs.rst 为骨架结合仓库中的构建脚本、Sphinx 扩展与配置系统讲解 SQLFluff 文档的编写规范、reStructuredText 语法要点、跨文档引用Cross-referencing机制以及自动生成文档的底层原理帮助贡献者快速上手并写出能被 CI 校验通过的文档。贡献文档被官方视为“最简单且最有帮助的贡献方式之一”——相比代码改动它需要的专业知识更少只需熟悉 SQLFluff 的日常用法而文档的读者面却极广。本文会从“两类文档形态”讲起逐步深入到ruff的 pydocstyle 校验、doc8的 rst 语法检查、generate-auto-docs.py的自动生成流程以及:ref:、:sqlfluff:ref:、:py:class:三种交叉引用语法最终让读者具备提交一份合格文档改动PR的完整能力。两类文档Docstring 与 Sphinx 独立文档SQLFluff 的文档体系分为两种形态两者在构建时又通过autodoc与自定义扩展产生交叉嵌入式文档Docstring位于函数、类和模块内的文档字符串主要服务面向开发者的使用场景因为它在开发者实际工作的代码库中直接可见、随手可得。独立文档Free-standing documentation即读者当前正在阅读的这份文档使用reStructuredText.rst编写由 Sphinx 构建并托管在docs.sqlfluff.com基于 ReadtheDocs 部署。两者并非完全割裂文档构建时借助autodoc扩展以及若干自定义集成直接从代码库中的 docstring 生成文档页面。最典型的例子是Rules Reference:ref:ruleref—— 规则参考CLI Reference:ref:cliref—— 命令行参考Dialects Reference:ref:dialectref—— 方言参考这三类页面本质上都是“从代码自动生成”的规则文档来自规则类自身的__doc__方言文档来自方言对象的docstringCLI 文档则通过sphinx_click从 Click 命令对象直接生成见 conf.py 中的 extensions 配置。想了解自定义集成如何工作可以参考仓库中的 docs/generate-auto-docs.py它是整个自动生成流程的核心入口。Docstring 规范ruff 的 pydocstyle 规则强制校验对于嵌入式文档SQLFluff 使用ruff的 pydocstyle 规则D系列强制要求 docstring 存在且格式正确并统一采用Google 风格 docstring。仓库中的实际配置位于 pyproject.toml[tool.ruff.lint] select [E4, E7, E9, F, I, D] # D105: Missing docstring in magic method # D107: Missing docstring in __init__ # D418: Function/ Method decorated with overload shouldn’t contain a docstring ignore [D107, D105, D418] [tool.ruff.lint.pydocstyle] convention google要点解读select中的D即 pydocstyle 规则组任何缺失 docstring 的函数、类、模块都会在 CI 中报错三个被忽略的规则是刻意豁免D107__init__缺失 docstring、D105魔法方法缺失 docstring、D418overload装饰的方法不应包含 docstring写入 docstring 反而会与项目约定冲突convention google指定了 Google 风格的 docstring 排版约定这是贡献者在写 docstring 时最需要遵守的格式。因此贡献者在新增或修改任何函数、类、模块时都应补全符合 Google 风格的 docstring例如参数Args:、返回值Returns:、异常Raises:等区块的规范写法。可以参阅sphinxcontrib-napoleon提供的 Google 风格示例来对齐格式细节。Sphinx 独立文档reStructuredText 语法与 doc8 校验独立文档使用 reStructuredText 编写文件后缀.rst构建工具是 Sphinx。对于不熟悉 reStructuredText 的贡献者Sphinx 官方提供了 reStructuredText 入门教程primer。在 CI 流程中SQLFluff 还引入了doc8来尽早发现 rst 语法问题。doc8 的配置同样位于 pyproject.toml[tool.doc8] # Ignore auto-generated docs ignore-path docs/source/_partials/注意_partials/目录被整体排除——该目录存放由脚本自动生成、仅供其他页面include的片段人工编写时无需也无法直接维护详见后文。reStructuredText 与 Markdown 的关键差异官方文档特别提醒reStructuredText 与更广为人知的 Markdown 非常相似但存在关键差异贡献者极易踩坑斜体与粗体*text with single asterisks*渲染为斜体加粗需要使用**double asterisks**。代码片段代码片段使用:code:...指令directive包裹而不是 Markdown 中常见的单个反引号...。裸反引号在 reStructuredText 中不是代码标记这是最常见的迁移错误之一。例如要展示行内代码应写作使用 :code:sqlfluff lint 命令对文件进行 lint。Sphinx 构建配置与流程独立文档由 docs/source/conf.py 驱动其中注册了 5 个扩展extensions [ # Autodocumentation from docstrings sphinx.ext.autodoc, # Allow Google style docstrings sphinx.ext.napoleon, # Documenting click commands sphinx_click.ext, # Redirects sphinx_reredirects, # SQLFluff domain sqlfluff_domain, ]这五个扩展恰好对应了上文提到的三类自动生成文档autodocnapoleon从 docstring 生成类/模块文档并支持 Google 风格解析sphinx_click生成 CLI 参考sqlfluff_domain是项目自研的规则文档域sphinx_reredirects维护了一组永久链接perma link重定向规则确保代码库与旧文档中的链接不因文档改版而失效例如perma/rule/{code}会重定向到具体规则的锚点。实际构建命令记录在 docs/Makefile 中每次构建前都会先执行python generate-auto-docs.py生成_partials/下的片段文件再调用sphinx-build并且默认带上-W --keep-going——即把警告当作错误处理同时尽量继续检查其余文档再以非零状态退出。这意味着贡献者提交的文档若存在未解析引用或格式警告构建会直接失败。跨文档引用Cross-referencing的三种语法这是 SQLFluff 文档中最具项目特色、也最需要掌握的技能。官方文档明确要求创建指向文档其他部分的链接时使用:ref:语法Sphinx 的 Cross-referencing 机制而不是硬编码页面路径。1. 方言引用:ref: 自动生成的锚点所有 SQL 方言的文档均由脚本自动生成并附带可供引用的锚点。例如要链接到 PostgreSQL 方言文档使用:ref:postgres_dialect_ref将postgres部分替换为你想要链接的方言name即可。这些锚点的生成逻辑见 docs/generate-auto-docs.pyf.write( f.. _{dialect.label}_dialect_ref:\n\n f{dialect.name}\n{- * len(dialect.name)}\n\n f**Label**: {dialect.label}\n\n )即每个方言都会生成形如.. _postgres_dialect_ref:的标签供全站任意位置引用非 ANSI 方言还会额外生成**Inherits from**: :ref:xxx_dialect_ref 的继承链说明。2. 规则引用:sqlfluff:ref: 自定义 Sphinx 域所有内置规则的文档由一个自定义 Sphinx 插件处理可以同时用规则代码或规则名称进行引用:sqlfluff:ref:LT01 :sqlfluff:ref:layout.spacing前者解析为规则LT01后者解析为规则layout.spacing。这一能力来自仓库中的 docs/source/_ext/sqlfluff_domain.pySQLFluffRule指令directive在文档中定义规则对象签名接受规则代码与名称两部分例如.. sqlfluff:rule:: AM01 ambiguous.distinct Write the documentation for the rule here.SQLFluffDomain域负责注册:sqlfluff:ref:交叉引用角色并在resolve_xref中同时按“代码”和“名称”两种签名解析目标因此两种写法都有效在add_target_and_index中4 位规则代码如LT01还会额外追加两个历史锚点sqlfluff.rules.Rule_LT01与sqlfluff.rules.sphinx.Rule_LT01以兼容旧版链接conf.py 中的重定向配置 进一步为每个规则代码生成了perma/rule/{code}永久链接。3. Python 类与模块引用:py:class: autodoc任意 Python 类与模块的文档由autodoc处理因此可以按其在文档中的名称直接引用。例如引用BaseRule基类:py:class:sqlfluff.core.rules.base.BaseRule还可以使用~前缀让渲染结果只显示短名称省略模块路径前缀:py:class:~sqlfluff.core.rules.base.BaseRule两种写法分别渲染为完整路径与短名如BaseRule。这与 rules.rst 中“规则索引由_partials/rule_table.rst与_partials/rule_summaries.rst自动 include”的机制相互配合构成了规则文档从 docstring 到网页的完整链路。自动生成文档的底层机制docs/generate-auto-docs.py是整个自动文档体系的发动机。其模块 docstring 说明该脚本在每次文档生成前运行通过导入 SQLFluff 并提取规则与方言数据生成docs/source/_partials/下的部分文档片段供其他章节以.. include::指令引用。例如它构建的rule_summaries.rst会被 docs/source/reference/rules.rst 以如下方式插入.. include:: ../_partials/rule_table.rst .. include:: ../_partials/rule_summaries.rst脚本的核心工作流分两大部分规则文档生成通过插件管理器get_plugin_manager().hook.get_rules()收集所有规则含第三方插件注册的规则按规则名称的bundle如aliasing、layout、capitalisation等分组随后写出_partials/rule_list.json规则代码与名称的清单供重定向与索引使用_partials/rule_table.rst规则汇总表格含 Bundle、Rule Name、Code、是否为 Core Rule 四列core 规则以✓标记_partials/rule_summaries.rst每个规则的详细小节内容直接取自规则类的__doc__rule.__doc__.partition(\n)分离标题与正文并为每个规则生成.. sqlfluff:rule:: {code} {name}指令供交叉引用。方言文档生成通过sqlfluff.list_dialects()收集所有方言强制将ansi排在最前其余按继承关系排序生成_partials/dialect_summaries.rst包含方言名称、label、继承来源Inherits from与 docstring同时为每个方言生成.. _{label}_dialect_ref:锚点。从源码结构看这一设计让“新增一条规则/方言的文档”几乎是零成本的贡献者只需在规则类或方言对象中写好符合 Google 风格的 docstring构建时即被自动提取、排版、建立锚点并纳入交叉引用体系无需手写任何 rst 页面。这也是为什么项目强调 docstring 必须规范——它不仅是代码质量要求更是文档系统的直接输入。贡献文档的实操清单综合以上机制向 SQLFluff 贡献文档的推荐流程如下定位文档类型开发者向内容类、函数、模块的行为说明写在 docstring 中采用 Google 风格并确保通过ruff的D系列检查用户向内容配置说明、使用指南、参考页写在docs/source/下的.rst文件中。遵守 rst 语法规范斜体用*...*、粗体用**...**、行内代码用:code:...新增页面按 Sphinx 约定添加标题层级与下划线。使用交叉引用而非硬编码链接方言用:ref:dialect_label_ref、规则用 :sqlfluff:ref:CODE或:sqlfluff:ref:bundle.name、Python 对象用:py:class:等 autodoc 角色不确定锚点时先运行文档构建查看生成的_partials/内容。本地验证在docs/目录下执行make html或 Windows 下make.bat html构建会先运行generate-auto-docs.py再调用sphinx-build -W --keep-going任何未解析引用、doc8 格式问题或 docstring 缺失都会导致构建失败这正是 CI 的校验标准。提交前自查确认没有触碰_partials/下由脚本生成的文件doc8 已将其列入忽略路径如修改了规则或方言本身需重新生成片段并检查其输出是否符合预期。通过以上流程即使是对 Sphinx 与 reStructuredText 尚不熟悉的贡献者也能借助 CI 的强校验与自动生成机制安全地为 SQLFluff 的文档体系添砖加瓦——而这正是官方文档所提倡的“最简单也最有帮助”的贡献路径。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SQLFluff 文档贡献指南：从 Docstring 到 Sphinx 自动生成文档的完整实践
SQLFluff 文档贡献指南从 Docstring 到 Sphinx 自动生成文档的完整实践【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluffSQLFluff 的官方文档由两部分构成嵌入在函数与模块docstring中的开发向文档以及由 Sphinx 构建、托管在docs.sqlfluff.com的独立文档。本文以 docs/source/guides/contributing/docs.rst 为骨架结合仓库中的构建脚本、Sphinx 扩展与配置系统讲解 SQLFluff 文档的编写规范、reStructuredText 语法要点、跨文档引用Cross-referencing机制以及自动生成文档的底层原理帮助贡献者快速上手并写出能被 CI 校验通过的文档。贡献文档被官方视为“最简单且最有帮助的贡献方式之一”——相比代码改动它需要的专业知识更少只需熟悉 SQLFluff 的日常用法而文档的读者面却极广。本文会从“两类文档形态”讲起逐步深入到ruff的 pydocstyle 校验、doc8的 rst 语法检查、generate-auto-docs.py的自动生成流程以及:ref:、:sqlfluff:ref:、:py:class:三种交叉引用语法最终让读者具备提交一份合格文档改动PR的完整能力。两类文档Docstring 与 Sphinx 独立文档SQLFluff 的文档体系分为两种形态两者在构建时又通过autodoc与自定义扩展产生交叉嵌入式文档Docstring位于函数、类和模块内的文档字符串主要服务面向开发者的使用场景因为它在开发者实际工作的代码库中直接可见、随手可得。独立文档Free-standing documentation即读者当前正在阅读的这份文档使用reStructuredText.rst编写由 Sphinx 构建并托管在docs.sqlfluff.com基于 ReadtheDocs 部署。两者并非完全割裂文档构建时借助autodoc扩展以及若干自定义集成直接从代码库中的 docstring 生成文档页面。最典型的例子是Rules Reference:ref:ruleref—— 规则参考CLI Reference:ref:cliref—— 命令行参考Dialects Reference:ref:dialectref—— 方言参考这三类页面本质上都是“从代码自动生成”的规则文档来自规则类自身的__doc__方言文档来自方言对象的docstringCLI 文档则通过sphinx_click从 Click 命令对象直接生成见 conf.py 中的 extensions 配置。想了解自定义集成如何工作可以参考仓库中的 docs/generate-auto-docs.py它是整个自动生成流程的核心入口。Docstring 规范ruff 的 pydocstyle 规则强制校验对于嵌入式文档SQLFluff 使用ruff的 pydocstyle 规则D系列强制要求 docstring 存在且格式正确并统一采用Google 风格 docstring。仓库中的实际配置位于 pyproject.toml[tool.ruff.lint] select [E4, E7, E9, F, I, D] # D105: Missing docstring in magic method # D107: Missing docstring in __init__ # D418: Function/ Method decorated with overload shouldn’t contain a docstring ignore [D107, D105, D418] [tool.ruff.lint.pydocstyle] convention google要点解读select中的D即 pydocstyle 规则组任何缺失 docstring 的函数、类、模块都会在 CI 中报错三个被忽略的规则是刻意豁免D107__init__缺失 docstring、D105魔法方法缺失 docstring、D418overload装饰的方法不应包含 docstring写入 docstring 反而会与项目约定冲突convention google指定了 Google 风格的 docstring 排版约定这是贡献者在写 docstring 时最需要遵守的格式。因此贡献者在新增或修改任何函数、类、模块时都应补全符合 Google 风格的 docstring例如参数Args:、返回值Returns:、异常Raises:等区块的规范写法。可以参阅sphinxcontrib-napoleon提供的 Google 风格示例来对齐格式细节。Sphinx 独立文档reStructuredText 语法与 doc8 校验独立文档使用 reStructuredText 编写文件后缀.rst构建工具是 Sphinx。对于不熟悉 reStructuredText 的贡献者Sphinx 官方提供了 reStructuredText 入门教程primer。在 CI 流程中SQLFluff 还引入了doc8来尽早发现 rst 语法问题。doc8 的配置同样位于 pyproject.toml[tool.doc8] # Ignore auto-generated docs ignore-path docs/source/_partials/注意_partials/目录被整体排除——该目录存放由脚本自动生成、仅供其他页面include的片段人工编写时无需也无法直接维护详见后文。reStructuredText 与 Markdown 的关键差异官方文档特别提醒reStructuredText 与更广为人知的 Markdown 非常相似但存在关键差异贡献者极易踩坑斜体与粗体*text with single asterisks*渲染为斜体加粗需要使用**double asterisks**。代码片段代码片段使用:code:...指令directive包裹而不是 Markdown 中常见的单个反引号...。裸反引号在 reStructuredText 中不是代码标记这是最常见的迁移错误之一。例如要展示行内代码应写作使用 :code:sqlfluff lint 命令对文件进行 lint。Sphinx 构建配置与流程独立文档由 docs/source/conf.py 驱动其中注册了 5 个扩展extensions [ # Autodocumentation from docstrings sphinx.ext.autodoc, # Allow Google style docstrings sphinx.ext.napoleon, # Documenting click commands sphinx_click.ext, # Redirects sphinx_reredirects, # SQLFluff domain sqlfluff_domain, ]这五个扩展恰好对应了上文提到的三类自动生成文档autodocnapoleon从 docstring 生成类/模块文档并支持 Google 风格解析sphinx_click生成 CLI 参考sqlfluff_domain是项目自研的规则文档域sphinx_reredirects维护了一组永久链接perma link重定向规则确保代码库与旧文档中的链接不因文档改版而失效例如perma/rule/{code}会重定向到具体规则的锚点。实际构建命令记录在 docs/Makefile 中每次构建前都会先执行python generate-auto-docs.py生成_partials/下的片段文件再调用sphinx-build并且默认带上-W --keep-going——即把警告当作错误处理同时尽量继续检查其余文档再以非零状态退出。这意味着贡献者提交的文档若存在未解析引用或格式警告构建会直接失败。跨文档引用Cross-referencing的三种语法这是 SQLFluff 文档中最具项目特色、也最需要掌握的技能。官方文档明确要求创建指向文档其他部分的链接时使用:ref:语法Sphinx 的 Cross-referencing 机制而不是硬编码页面路径。1. 方言引用:ref: 自动生成的锚点所有 SQL 方言的文档均由脚本自动生成并附带可供引用的锚点。例如要链接到 PostgreSQL 方言文档使用:ref:postgres_dialect_ref将postgres部分替换为你想要链接的方言name即可。这些锚点的生成逻辑见 docs/generate-auto-docs.pyf.write( f.. _{dialect.label}_dialect_ref:\n\n f{dialect.name}\n{- * len(dialect.name)}\n\n f**Label**: {dialect.label}\n\n )即每个方言都会生成形如.. _postgres_dialect_ref:的标签供全站任意位置引用非 ANSI 方言还会额外生成**Inherits from**: :ref:xxx_dialect_ref 的继承链说明。2. 规则引用:sqlfluff:ref: 自定义 Sphinx 域所有内置规则的文档由一个自定义 Sphinx 插件处理可以同时用规则代码或规则名称进行引用:sqlfluff:ref:LT01 :sqlfluff:ref:layout.spacing前者解析为规则LT01后者解析为规则layout.spacing。这一能力来自仓库中的 docs/source/_ext/sqlfluff_domain.pySQLFluffRule指令directive在文档中定义规则对象签名接受规则代码与名称两部分例如.. sqlfluff:rule:: AM01 ambiguous.distinct Write the documentation for the rule here.SQLFluffDomain域负责注册:sqlfluff:ref:交叉引用角色并在resolve_xref中同时按“代码”和“名称”两种签名解析目标因此两种写法都有效在add_target_and_index中4 位规则代码如LT01还会额外追加两个历史锚点sqlfluff.rules.Rule_LT01与sqlfluff.rules.sphinx.Rule_LT01以兼容旧版链接conf.py 中的重定向配置 进一步为每个规则代码生成了perma/rule/{code}永久链接。3. Python 类与模块引用:py:class: autodoc任意 Python 类与模块的文档由autodoc处理因此可以按其在文档中的名称直接引用。例如引用BaseRule基类:py:class:sqlfluff.core.rules.base.BaseRule还可以使用~前缀让渲染结果只显示短名称省略模块路径前缀:py:class:~sqlfluff.core.rules.base.BaseRule两种写法分别渲染为完整路径与短名如BaseRule。这与 rules.rst 中“规则索引由_partials/rule_table.rst与_partials/rule_summaries.rst自动 include”的机制相互配合构成了规则文档从 docstring 到网页的完整链路。自动生成文档的底层机制docs/generate-auto-docs.py是整个自动文档体系的发动机。其模块 docstring 说明该脚本在每次文档生成前运行通过导入 SQLFluff 并提取规则与方言数据生成docs/source/_partials/下的部分文档片段供其他章节以.. include::指令引用。例如它构建的rule_summaries.rst会被 docs/source/reference/rules.rst 以如下方式插入.. include:: ../_partials/rule_table.rst .. include:: ../_partials/rule_summaries.rst脚本的核心工作流分两大部分规则文档生成通过插件管理器get_plugin_manager().hook.get_rules()收集所有规则含第三方插件注册的规则按规则名称的bundle如aliasing、layout、capitalisation等分组随后写出_partials/rule_list.json规则代码与名称的清单供重定向与索引使用_partials/rule_table.rst规则汇总表格含 Bundle、Rule Name、Code、是否为 Core Rule 四列core 规则以✓标记_partials/rule_summaries.rst每个规则的详细小节内容直接取自规则类的__doc__rule.__doc__.partition(\n)分离标题与正文并为每个规则生成.. sqlfluff:rule:: {code} {name}指令供交叉引用。方言文档生成通过sqlfluff.list_dialects()收集所有方言强制将ansi排在最前其余按继承关系排序生成_partials/dialect_summaries.rst包含方言名称、label、继承来源Inherits from与 docstring同时为每个方言生成.. _{label}_dialect_ref:锚点。从源码结构看这一设计让“新增一条规则/方言的文档”几乎是零成本的贡献者只需在规则类或方言对象中写好符合 Google 风格的 docstring构建时即被自动提取、排版、建立锚点并纳入交叉引用体系无需手写任何 rst 页面。这也是为什么项目强调 docstring 必须规范——它不仅是代码质量要求更是文档系统的直接输入。贡献文档的实操清单综合以上机制向 SQLFluff 贡献文档的推荐流程如下定位文档类型开发者向内容类、函数、模块的行为说明写在 docstring 中采用 Google 风格并确保通过ruff的D系列检查用户向内容配置说明、使用指南、参考页写在docs/source/下的.rst文件中。遵守 rst 语法规范斜体用*...*、粗体用**...**、行内代码用:code:...新增页面按 Sphinx 约定添加标题层级与下划线。使用交叉引用而非硬编码链接方言用:ref:dialect_label_ref、规则用 :sqlfluff:ref:CODE或:sqlfluff:ref:bundle.name、Python 对象用:py:class:等 autodoc 角色不确定锚点时先运行文档构建查看生成的_partials/内容。本地验证在docs/目录下执行make html或 Windows 下make.bat html构建会先运行generate-auto-docs.py再调用sphinx-build -W --keep-going任何未解析引用、doc8 格式问题或 docstring 缺失都会导致构建失败这正是 CI 的校验标准。提交前自查确认没有触碰_partials/下由脚本生成的文件doc8 已将其列入忽略路径如修改了规则或方言本身需重新生成片段并检查其输出是否符合预期。通过以上流程即使是对 Sphinx 与 reStructuredText 尚不熟悉的贡献者也能借助 CI 的强校验与自动生成机制安全地为 SQLFluff 的文档体系添砖加瓦——而这正是官方文档所提倡的“最简单也最有帮助”的贡献路径。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考