GitLab Documentation guidelines

原文：https://docs.gitlab.com/ee/development/documentation/

GitLab Documentation guidelines

GitLab 的文档旨在作为唯一的真实来源（SSOT） ，提供有关如何配置，使用 GitLab 以及对其进行故障排除的信息. 该文档包含按产品领域和主题组织的每个 GitLab 功能的用例和使用说明. 这包括跨多个 GitLab 功能的主题和工作流程，以及将 GitLab 与其他应用程序一起使用.

除了此页面之外，以下资源还可以帮助您编写文档并做出贡献：

Source files and rendered web locations

有关 GitLab，GitLab Runner，Omnibus GitLab 和 Charts 的文档已发布到https://docs.gitlab.com . GitLab 的文档也发布在 GitLab 实例域的/help内的应用程序中. 在/help ，仅包含当前版本和版本的帮助. 有关其他版本的帮助，请访问https://docs.gitlab.com/archives/ .

文档的源位于以下仓库位置的每个 GitLab 应用程序的代码库中：

Project Path
GitLab /doc
GitLab Runner /docs
Omnibus GitLab /doc
Charts /doc

文档问题和合并请求是它们各自存储库的一部分，都带有标签Documentation .

Branch naming

GitLab 主项目的CI 管道配置为仅自动运行与贡献类型匹配的作业. 如果您的贡献仅包含文档更改，那么将仅运行与文档相关的作业，并且管道的完成将比代码贡献更快.

如果要向 Runner，Omnibus 或 Charts 提交仅文档更改，则不会自动确定快速管道. 相反，请使用以下指南为仅文档合并请求创建分支：

分店名称 有效的例子
从docs/开始 docs/update-api-issues
从docs-开始 docs-update-api-issues
以-docs 123-update-api-issues-docs

Contributing to docs

整个 GitLab 社区都欢迎对 GitLab 文档做出贡献 .

为确保 GitLab 文档是最新的，所有功能更改都有特殊的流程和职责，即影响功能外观，使用或管理的开发工作.

但是，任何人都可以贡献与功能更改无关的文档改进 . 例如，添加有关如何完成用例的新文档，这可以通过 GitLab 或第三方工具和 GitLab 完成.

Markdown and styles

GitLab 文档使用GitLab Kramdown作为其 Markdown 渲染引擎. 有关完整的 Kramdown 参考，请参阅《 GitLab Markdown 指南》 .

遵守文档样式指南 . 如果缺少样式标准，欢迎您通过合并请求提出建议.

Folder structure and files

请参阅” 文档样式指南”的” 结构”部分.

Metadata

为了提供其他指令或有用的信息，我们将 YAML 格式的元数据添加到每个产品文档页面的开头（YAML 开头）. 所有值均视为字符串，仅用于docs 网站 .

Stage and group metadata

理想情况下，每个页面都应具有与其所属的阶段和组相关的元数据，以及如下所述的信息块：

  • stage ：页面大部分内容所属的Stage .
  • group ：页面大部分内容所属的Group .

  • info ：下一行，为与该页面的舞台和小组相关的技术作家联系提供指导，以帮助参与者：

    1. To determine the technical writer assigned to the Stage/Group
    2. associated with this page, see
    3. https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers

例如，以下元数据将位于产品文档页面的开始，其内容主要与”审核事件”功能相关：

  1. ---
  2. stage: Monitor
  3. group: APM
  4. info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
  5. ---

Page type metadata

最初在此史诗中讨论过，每个页面应该具有type元数据. 可以是以下一项或多项：

  • index ：索引/概述页面. 它们充当其他页面的列表. 不一定意味着页面应命名为index.md . 示例页面 .
  • concepts ：使用产品之前需要了解的内容. 信息性的，非指导性的. 例如，抽象的想法，解释含义或收益，支持对任务的理解. 阅读它们以获取背景信息，例如”为什么 X 很重要”. 示例页面 .
  • howto ：特定用例说明. 示例页面 .
  • tutorial ：边做边学过程/概念. 示例页面 .
  • reference ：介绍什么是/做什么. 诸如特定设置，没有太多解释的事实之类的东西可以阅读以获取详细信息. 示例页面 .

Redirection metadata

将页面移到另一个位置时，应添加以下元数据：

  • redirect_to ：访问者应将移动页面重定向到的相对路径和文件名（扩展名为.md ）. 了解更多 .
  • disqus_identifier ：Disqus 评论系统的标识符. 用于保留已被移至新 URL 的页面的注释. 了解更多 .

Comments metadata

docs 网站上默认启用了注释（由 Disqus 提供）. 如果要禁用它们（例如在索引页面中），请将其设置为false ：

  1. ---
  2. comments: false
  3. ---

Additional page metadata

每个页面可以具有其他（可选）元数据（在default.html Nanoc 布局中设置），如果定义，这些元数据将显示在页面顶部：

  • author ：页面author的名称，通常是教程. 它需要author_gitlab才能显示.
  • author_gitlab ：GitLab.com 上作者的用户名. 它需要author才能显示.
  • date ：页面的创建日期，通常用于教程.
  • article_type ：文章的类型. 可以是tutorial或user guide .
  • level ：操作方法或教程的复杂程度. 可以是beginner ， advanced或intermediate .
  • last_updated ：页面上次更新时的 ISO 格式日期. 例如2020-02-14 .
  • reading_time ：如果要添加页面的大概阅读时间的指示，可以将reading_time设置为true . 这使用简单的算法根据单词数计算阅读时间.

Changing document location

更改文档的位置需要特定的步骤，以确保用户可以无缝访问新的文档页面，无论他们是通过/help还是通过https://docs.gitlab.com访问 GitLab 实例域上的内容. 如果您在此过程中有任何疑问（例如是否需要搬迁），请务必指派一名技术作家，并确保在合并之前技术作家会对此更改进行审查.

如果确实需要更改文档的位置，请不要删除旧文档，而应将所有内容替换为以下内容：

  1. ---
  2. redirect_to: '../path/to/file/index.md'
  3. ---
  5. This document was moved to [another location](../path/to/file/index.md).

其中../path/to/file/index.md通常是旧文档的相对路径.

所述redirect_to变量同时支持完整或相对 URL，例如https://docs.gitlab.com/ee/path/to/file.html ， ../path/to/file.html ， path/to/file.md . 它确保重定向将对https://docs.gitlab.com起作用，并且任何*.md路径都将编译为*.html . 前部事项下方的新行通知用户文档已更改位置，对于从存储库浏览该文件的用户而言非常有用.

例如，如果将doc/workflow/lfs/index.md移到doc/administration/lfs.md ，则步骤将是：

  1. Copy doc/workflow/lfs/index.md to doc/administration/lfs.md

  2. 将doc/workflow/lfs/index.md的内容替换为：

    1. ---
    2. redirect_to: '../../administration/lfs.md'
    3. ---
    5. This document was moved to [another location](../../administration/lfs.md).

  3. 查找并用新位置替换所有出现的旧位置. 查找它们的快速方法是在将文件从以下位置更改的存储库中使用git grep ：

    1. git grep -n "workflow/lfs/lfs_administration"
    2. git grep -n "lfs/lfs_administration"

注意：如果要移动的文档上有任何 Disqus 评论，则要执行的其他步骤如下所示 .

注意事项：

  • 由于除了文档本身以外，我们还使用内联文档，因此该文档也可能在访问/help时将呈现的 GitLab（ app/ ）视图中引用，有时甚至在测试套件（ spec/ ）中也会引用. 您必须在这些路径中搜索对文档的引用并进行更新.
  • 上面的git grep命令将在您在其中运行它的目录中以递归方式搜索workflow/lfs/lfs_administration和lfs/lfs_administration ，并将打印文件和提及该文件的行. 您可能会问为什么这两次抱怨. 由于我们使用相对路径链接到文档 ，因此有时更深入地搜索路径可能很有用.
  • 当文档链接到 GitLab 的内置帮助页面时，不使用*.md扩展名，这就是为什么我们在git grep忽略它.
  • 使用”更改文档位置” MR 描述模板上的清单.

Redirections for pages with Disqus comments

如果要重定位的文档页面已经包含 Disqus 评论，则我们需要保留 Disqus 线程.

Disqus 使用每页标识符，对于https://docs.gitlab.com ，页面标识符被配置为页面 URL. 因此，当我们更改文档位置时，我们需要将旧的 URL 保留为相同的 Disqus 标识符.

为此，将变量disqus_identifier添加到disqus_identifier ，使用旧的 URL 作为值. 例如，假设我们将https://docs.gitlab.com/my-old-location/README.html下可用的文档移到了新位置https://docs.gitlab.com/my-new-location/index.html .

在新文档的开头部分，我们添加了以下内容：

  1. ---
  2. disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html'
  3. ---

注：有必要在文件名中disqus_identifier URL，即使它index.html或README.html .

Merge requests for GitLab documentation

在开始之前，请确保您已阅读上面的” 为文档做贡献 “介绍性部分和文档工作流程 .

  • 使用当前的合并请求描述模板
  • 标记 MR Documentation （只能由具有developer访问权限的developer （例如，GitLab 团队成员）完成）
  • 在下面的每个注释中分配正确的里程碑（只能由具有developer访问权限的人（例如，GitLab 团队成员）完成）

如果对现有内容进行了改进，文档将被合并，这代表了遵循模板和样式标准的真诚努力，并且被认为是准确的.

对于进一步完善文档的进一步需求，应在后续的 MR 或问题中立即解决.

注意：如果要添加文档的发行版已经冻结或发行，请使用标签~"Pick into XY"将其合并到正确的发行版中. 尽量避免选择过去的发行版，因为这样做会增加发行版管理器的工作量.

GitLab /help

每个 GitLab 实例都包含文档，该文档可从/help （ https://gitlab.example.com/help ）获得. 例如， https://gitlab.com/help .

https://docs.gitlab.com上在线提供的文档每隔四个小时从 GitLab，Omnibus 和 Runner 的master分支进行部署. 因此，合并请求合并后，它将在同一天在线可用. 但是，它将在分配给 MR 的里程碑内发货（并在/help上可用）.

例如，假设您的合并请求的里程碑设置为 11.3，该里程碑将于 2018-09-22 发布. 如果在 2018-09-15 合并，它将在 2018-09-15 联机提供，但是，随着功能冻结日期的过去，如果 MR 没有~"Pick into 11.3"标签，那么该里程碑必须更改为 11.4，并且仅在 2018-10-22 以及 GitLab 11.4 中将与所有 GitLab 软件包一起提供. 这意味着，它将仅在 GitLab 11.4 及更高版本的/help下提供，但在合并的同一天在https://docs.gitlab.com/上提供.

Linking to /help

构建新功能时，可能需要从应用程序 GitLab 链接文档. 通常，这是通过help_page_path helper 方法在app/views/目录内的文件中完成的.

以最简单的形式，用于生成到/help页面的链接的 HAML 代码为：

  1. = link_to 'Help page', help_page_path('user/permissions')

help_page_path使用以下约定包含要链接到的文档的路径：

  • 它相对于 GitLab 存储库中的doc/目录
  • .md扩展名必须省略
  • 它不能以斜杠（ / ）结尾

以下是根据情况应使用的一些特殊情况. 您可以结合以下一项或多项：

  1. 链接到锚链接. 使用anchor作为help_page_path方法的一部分：

    1. = link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')

  2. 在新标签页中打开链接. 这应该是默认行为：

    1. = link_to 'Help page', help_page_path('user/permissions'), target: '_blank'

  3. 链接到圆圈图标. 通常用于无法使用长描述的设置，例如复选框旁边. 您基本上可以使用任何字体超赞的图标，但更喜欢使用question-circle ：

    1. = link_to icon('question-circle'), help_page_path('user/permissions')

  4. 使用按钮链接. 在文本与页面布局其余部分脱离上下文的地方很有用：

    1. = link_to 'Help page', help_page_path('user/permissions'),  class: 'btn btn-info'

  5. 使用内联某些文本的链接.

    1. Description to #{link_to 'Help page', help_page_path('user/permissions')}.

  6. 在句子末尾添加句点. Useful when you don’t want the period to be part of the link:

    1. = succeed '.' do
    2.   Learn more in the
    3.   = link_to 'Help page', help_page_path('user/permissions')

GitLab /help tests

运行了一些RSpec 测试以确保 GitLab 文档能够呈现并正常工作. 特别是，该主要文档的登录页面将从/help正确运行. 例如， GitLab.com 的/help .

Docs site architecture

请参阅” 文档”网站的体系结构页面，以了解我们如何在https://docs.gitlab.com 上构建和部署该网站，并查看所有正在使用的资产和库.

Global navigation

有关如何构建和更新左侧导航菜单的信息，请参阅全局导航文档.

Previewing the changes live

注意：要在本地预览对文档的更改，请遵循本开发指南或GDK 的这些说明 .

当前为以下项目启用了实时预览：

如果您的合并请求中有 docs 更改，则可以使用手动review-docs-deploy作业为合并请求部署 docs review 应用. 您将至少需要维护者权限才能运行它.

Manual trigger a docs build

注意：您将需要将分支推送到这些存储库，它不适用于 fork.

review-docs-deploy*工作将：

  1. 在gitlab-docs项目中创建一个以该方案命名的新分支： docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID ，其中DOCS_GITLAB_REPO_SUFFIX是每个产品的后缀，例如ee表示 EE， omnibus表示 Omnibus CI_MERGE_REQUEST_IID ， CI_MERGE_REQUEST_IID等，相应合并请求的 ID.
  2. 触发跨项目管道，并使用您的更改构建文档站点.

如果评论应用程序 URL 返回 404，则意味着该站点尚未部署，或者远程管道出了点问题. 给它几分钟，它应该在线显示，否则，您可以从合并请求的作业输出中的链接检查远程管道的状态. 如果管道失败或阻塞，请在#docs聊天频道中添加一行.

提示：对 GitLab 项目没有合并权限的人（想想贡献者的分支）不能运行手动作业. 在这种情况下，您可以请 GitLab 团队的某人授权为您执行此操作.注意：确保始终删除正在处理的合并请求的分支. 如果您不这样做，那么远程 docs 分支也不会被删除，并且承载 Review Apps 的服务器最终将没有磁盘空间.

Troubleshooting review apps

如果评论应用程序 URL 返回 404，请按照以下步骤进行调试：

  1. 您是否遵循了合并请求小部件中的 URL？ 如果是，则检查链接是否与作业输出中的链接相同.
  2. 您是否遵循作业输出中的 URL？ 如果是，则意味着该站点尚未部署或远程管道出了点问题. 给它几分钟，它应该在线显示，否则，您可以从作业输出中的链接检查远程管道的状态. 如果管道失败或阻塞，请在#docs聊天频道中添加一行.

Technical aspects

如果您想了解更深入的细节，这就是实际发生的事情：

  1. 您在合并请求中手动运行review-docs-deploy作业.
  2. The job runs the scripts/trigger-build-docs script with the deploy flag, which in turn:
    1. 使用您的分支名称并应用以下内容：
      • docs-preview-前缀已添加.
      • 产品信息用于了解评论应用所源自的项目.
      • 添加了合并请求的编号，以便您可以通过gitlab-docs分支名称知道其源自的合并请求.
    2. The remote branch is then created if it doesn’t exist (meaning you can re-run the manual job as many times as you want and this step will be skipped).
    3. 在 docs 项目中触发了新的跨项目管道.
    4. 预览 URL 显示在作业输出和合并请求小部件中. 您还将获得到远程管道的链接.
  3. 在 docs 项目中，创建了管道，它跳过了测试作业以减少构建时间.
  4. 构建了 docs 网站之后，HTML 文件即作为工件上传.
  5. 仅与 docs 项目相关联的特定 Runner，运行 Review App 作业，该作业下载工件，并使用rsync将文件传输到 NGINX 为它们提供文件的位置.

The following GitLab features are used among others:

Testing

我们将文档视为代码，因此在 CI 管道中使用测试来维护文档的标准和质量. 提交带有新文档或更改文档的合并请求时，当前测试在 CI 作业中运行，它们是：

  • docs lint ：对 docs 本身的内容运行一些测试：
    • lint-doc.sh脚本运行以下检查和操作：
      • 所有 cURL 示例都使用长标记（例如：— --header ，而不是-H ）.
      • CHANGELOG.md不包含重复的版本.
      • doc/中没有文件是可执行文件.
      • 没有添加新的README.md .
      • markdownlint .
      • 谷
    • Nanoc 测试：
      • internal_links检查所有内部链接（例如： [link](../index.md) ）是否有效.
      • internal_anchors检查所有内部锚点（例如： [link](../index.md#internal_anchor) ）是否有效.

Running tests

除了在本地预览更改之外，您还可以在本地运行所有棉绒检查和 Nanoc 测试.

Nanoc tests

要在本地执行 Nanoc 测试：

  1. 导航到gitlab-docs目录.

  2. Run:

    1. # Check for broken internal links
    2. bundle exec nanoc check internal_links
    4. # Check for broken external links (might take a lot of time to complete).
    5. # This test is set to be allowed to fail and is run only in the gitlab-docs project CI
    6. bundle exec nanoc check internal_anchors

Lint checks

Lint 检查由lint-doc.sh脚本执行，可以按以下方式执行：

  1. 导航到gitlab目录.

  2. Run:

    1. MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh

MD_DOC_PATH指向您要运行 lint 检查的文件或目录的位置. 如果完全省略它，它将默认为doc/目录. 输出应类似于：

  1. => Linting documents at path /path/to/gitlab as <user>...
  2. => Checking for cURL short options...
  3. => Checking for CHANGELOG.md duplicate entries...
  4. => Checking /path/to/gitlab/doc for executable permissions...
  5. => Checking for new README.md files...
  6. => Linting markdown style...
  7. => Linting prose...
  8. ✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
  9. ✔ Linting passed

请注意，这要求您要么在计算机上安装了必需的 lint 工具，要么在运行的 Docker 安装中，在这种情况下，将使用预安装了这些工具的映像.

Local linters

为了帮助您遵守文档样式指南 ，并改善添加到文档中的内容， 请安装文档短绒 ， 并将其与代码编辑器集成 .

在 GitLab，我们主要使用：

markdownlint

markdownlint检查 Markdown 语法是否遵循某些规则 ，并由docs-lint测试使用 .

我们的文档样式指南和Markdown 指南详细说明了为 GitLab 文档选择 Markdown 语法时必须进行哪些选择. 该工具有助于发现与这些准则的偏差.

在以下项目中找到 markdownlint 配置：

在构建管道中也使用此配置.

您可以使用 markdownlint：

Vale

淡水河谷是英语的语法，样式和单词用法惯用语. Vale 的配置存储在项目根目录下的.vale.ini文件中.

Vale 支持创建可扩展多种检查类型的自定义测试 ，我们将这些检查存储在项目文档目录的.linting/vale/styles/gitlab目录中.

在以下项目中找到 Vale 配置：

在构建管道中也使用此配置.

您可以使用 Vale：

Install linters

至少要安装markdownlint和Vale以匹配在构建管道中运行的检查：

  1. 使用以下任一方法安装markdownlint-cli ：

    • npm:

      1. npm install -g markdownlint-cli

    • yarn:

      1. yarn global add markdownlint-cli

      我们建议安装 linting Docker image文档中当前使用的markdownlint-cli版本.

  2. 安装vale . 例如，要使用brew for macOS 安装，请运行：

    1. brew install vale

    We recommend installing the version of Vale currently used in the documentation linting Docker image.

除了在命令行上使用 markdownlint 和 Vale 之外，这些工具还可以与代码编辑器集成 .

Configure editors

要在编辑器中配置 markdownlint，请根据需要安装以下之一：

要在编辑器中配置 Vale，请根据需要安装以下任一程序：

我们不使用Vale Server .

Disable Vale tests

您可以为文档的任何部分禁用特定的 Vale 棉绒规则或所有 Vale 棉绒规则：

  • 要禁用特定规则，添加<!-- vale gitlab.rulename = NO -->文本之前标记和<!-- vale gitlab.rulename = YES -->后的文字标签，更换rulename与GitLab 样式目录中测试的文件名.
  • 要禁用所有淡水河谷棉绒规则，请在文本前添加<!-- vale off -->淡水<!-- vale off -->标签，并在文本后添加<!-- vale off -->淡水<!-- vale on -->标签.

只要有可能，仅排除有问题的规则和行. 在某些情况下，例如列表项，您可能需要禁用整个列表的绒毛，直到Vale 问题＃175得到解决.

有关更多信息，请参见Vale 的文档 .

Danger Bot

GitLab 在代码审查中的某些元素上使用了Danger . 对于文档在合并请求中的更改，每当对/doc下的文件进行更改时，Danger Bot 都会在注释中留下有关文档处理的进一步说明. 这是在 GitLab 存储库中的Dangerfile中/ danger / documentation /下配置的 .