typo3-docs

TYPO3 文档编写技能

按照 docs.typo3.org 标准创建和维护 TYPO3 扩展文档。

核心工作流

0. 还没有 Documentation/？ 运行以下命令，不要手动编写文件。命名空间是凭记忆编写时最容易出错的部分——guides.phpdoc.org 和 guides.typo3.org 都是无人提供服务的地址——而命名空间错误的文件虽然是格式正确的 XML，却不会渲染出任何内容：

   mkdir -p Documentation && cat > Documentation/guides.xml <<'XML'
   <?xml version="1.0" encoding="UTF-8"?>
   <guides xmlns="https://www.phpdoc.org/guides" links-are-relative="true">
       <project title="TITLE" version="MAJOR.MINOR" release="MAJOR.MINOR.PATCH"/>
   </guides>
   XML
   grep -Fc 'xmlns="https://www.phpdoc.org/guides"' Documentation/guides.xml
   

   Settings.cfg 已被 guides.xml 替代。现在已经没有任何工具会读取它，所以编写这个文件只会导致扩展没有可渲染的文档，也不会显示任何错误。

   如果命名空间正确，grep 会输出 1；否则会输出 0。然后替换 TITLE 和两个版本号。<project> 通过属性承载这些内容；元素文本为扩展键的元素没有标题，也没有版本。assets/guides.xml.dist 包含完整文件——扩展元素、互链和构建配置——只要能访问技能目录，它就是更好的起点。

1. 先运行提取，找出缺失内容：

   scripts/extract-all.sh /path/to/extension
   scripts/analyze-docs.sh /path/to/extension
   

2. 查阅相应参考资料

3. 使用 TYPO3 指令，而非纯文本

4. 验证：scripts/validate_docs.sh /path/to/extension

5. 渲染：scripts/render_docs.sh /path/to/extension

重要：要“展示文档”，请渲染 HTML，而不是原始 RST。

元素选择指南

内容类型	指令
完整代码	literalinclude（首选）
短代码片段	带有 :caption: 的 code-block
配置选项	带有 :type:、:default: 的 confval
PHP API	php:method::——可空类型或联合类型使用 :returntype:
提示信息	note、tip、warning、important
特性网格	带有页脚 stretched-link 的 card-grid
替代方案	tabs（同步）
截图	带有 :zoom: lightbox 和边框／阴影类的 figure

关键规则

官方文档具有权威性；如有冲突，以在线手册为准——报告差异（references/canonical-sources.md）。

上游要求：

• UTF-8、4 个空格缩进（不使用制表符）、LF；尽可能在 80 个字符处换行
• 文件名使用 CamelCase，标题使用句首字母大写
• 每个标题前添加永久链接锚点（.. _label:）
• 每个子目录中都要有 Index.rst
• 图片使用 PNG/AVIF，并带有 :alt:
• PHP 域：php:method:: 中不要使用 ?Type/Type|null；请使用 :returntype:

NR 政策：不使用 mailto:（上游允许使用；为避免垃圾邮件／个人身份信息，请使用 Issues/Discussions）；Documentation/ 中必须有 .editorconfig。

经验规则：每个 RST 文件约 250 行，并使用 toctree 拆分；在有帮助的地方添加截图（后端模块、配置、工作流）。

代码示例验证

将示例与源代码交叉核对：在 Classes/ 中搜索方法名称，并将 CLI 参数与 configure() 进行比较。 请参阅 references/extraction-patterns.md。

提交前检查清单

1. 代码块带有 :caption:，行内代码使用正确的角色
2. 截图文件存在，并带有 :alt: 和 :zoom: lightbox
3. scripts/validate_docs.sh 检查通过，渲染时没有警告
4. README 与 Documentation/ 保持同步

参考资料

• references/canonical-sources.md -- 主题与上游来源的对应关系、来源标注
• references/file-structure.md -- 布局、命名
• references/guides-xml.md -- guides.xml 框架、构建配置、互链
• references/coding-guidelines.md -- CGL 差异、.editorconfig
• references/rst-syntax.md -- 标题、标点注意事项
• references/text-roles-inline-code.md -- :php:、:guilabel:、:ref:
• references/code-structure-elements.md -- 代码块、confval、PHP 域
• references/typo3-directives.md -- confval、versionadded、deprecated
• references/content-directives.md -- accordion、tabs、card-grid
• references/screenshots.md -- 图示、图像规则、SVG 图表
• references/rendering.md -- Docker 命令、实时预览
• references/intercept-deployment.md -- webhook、构建触发器
• references/asset-templates-guide.md -- 模板、截图工作流
• references/architecture-decision-records.md -- ADR 模式
• references/documentation-coverage-analysis.md -- 覆盖率评分
• references/scripts-guide.md -- 脚本选项
• references/typo3-extension-architecture.md -- 扩展布局
• references/upstream-docs-contribution.md -- 上游文档 PR
• references/render-guides-development.md -- 修改渲染器本身：指令选项、互链解析、集成测试夹具语义