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 :文章的类型. 可以是tutorialuser guide .
  • level :操作方法或教程的复杂程度. 可以是beginneradvancedintermediate .
  • 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. ---
  4. 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.htmlpath/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. ---
    4. 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_administrationlfs/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.htmlREADME.html .

Merge requests for GitLab documentation

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

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

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

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

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

GitLab /help

每个 GitLab 实例都包含文档,该文档可从/helphttps://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_IIDCI_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
    3. # Check for broken external links (might take a lot of time to complete).
    4. # This test is set to be allowed to fail and is run only in the gitlab-docs project CI
    5. 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

至少要安装markdownlintVale以匹配在构建管道中运行的检查:

  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 -->后的文字标签,更换rulenameGitLab 样式目录中测试的文件名.
  • 要禁用所有淡水河谷棉绒规则,请在文本前添加<!-- vale off -->淡水<!-- vale off -->标签,并在文本后添加<!-- vale off -->淡水<!-- vale on -->标签.

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

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

Danger Bot

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