用途:为 Drupal contrib 模块编写和维护文档,使用 MkDocs(Material 主题)构建 docs/ 目录,并借助 drupal.org 的 gitlab_templates 流水线发布到 https://project.pages.drupalcode.org/<data_name>。data_name 为模块项目机器名,即 .info.yml 前缀与 git 仓库名。
主要能力:先阅读模块的 .info.yml、README、docs/、配置表单、路由与服务,弄清模块实际功能后再写文档;建立 docs/ 结构,入口为 docs/index.md;在仓库根目录维护 mkdocs.yml(site_name、site_url、theme: name: material 与 nav);处理 .gitlab-ci.yml;在 README.md 末尾追加一段指向 docs/ 与 GitLab Pages 的说明;必要时用 mermaid 画流程图、架构图、插件关系或状态机。
使用方式:docs/ 大致包含 index.md、installation.md、configuration.md、usage/<feature>.md;若模块提供扩展面(如 *.api.php、插件系统、事件订阅者),另设 developers/ 章节;若存在扩展本模块的其他模块,可加 extending-modules.md。mkdocs.yml 使用 markdown_extensions(attr_list、md_in_html、pymdownx.blocks.caption、pymdownx.superfences 的 mermaid 自定义 fence 及 admonition、toc、pymdownx.highlight)与 plugins(search、include-markdown)。Mermaid 无需额外安装;include-markdown 需在 pages job 添加 before_script: pip install mkdocs-include-markdown-plugin。CI 模板缺失时加入标准 include 配置,并在用户同意后决定是否跳过测试作业。
限制:不在 docs/ 之外放文档页;不覆盖已有 .gitlab-ci.yml;不伪造截图路径,截图需用户提供可访问站点与登录信息或已有浏览器工具;首次推送后需在 GitLab 页面关闭 unique ID;写作须避免 em dash、en dash、营销语气与 AI 腔。文档未提供具体模块示例与完整代码,使用时需结合具体模块资料。