- ソースファイルとレンダリングされたウェブの場所
- ドキュメントへの貢献者
- マークダウンとスタイル
- フォルダ構造とファイル
- メタデータ
- ドキュメントの場所の変更
- GitLab ドキュメントのマージリクエスト
-
GitLab
/help
- ドキュメント・サイト・アーキテクチャ
- 変更をライブでプレビュー
- テスト
- デンジャーボット
GitLab ドキュメンテーションガイドライン
GitLabのドキュメントは、GitLabの設定、使い方、トラブルシューティングの方法に関する情報を、(SSOT)、 単一の真実のソースとして提供することを目的としています。 ドキュメントには、すべてのGitLab機能のユースケースと使い方の説明が、製品分野やテーマごとにまとめられています。 これには、複数のGitLab機能にまたがるトピックやワークフロー、他のアプリケーションとのGitLabの使い方も含まれます。
このページに加え、以下のリソースは、あなたが文書を作成し貢献するのに役立ちます:
- スタイルガイド- ドキュメントに属するもの、言語ガイドライン、従うべきMarkdown標準、リンクなど。
- 構造とテンプレート- docページの典型的な部分と、それぞれの書き方を学びます。
- ドキュメンテーションプロセス。
- Markdown Guide- GitLabがサポートする全てのMarkdown構文のリファレンスです。
- サイトアーキテクチャ-https://docs.gitlab.com の構築方法。
- 機能フラグのドキュメント- 機能フラグの後ろにデプロイされたGitLab機能のドキュメントの書き方と更新方法。
ソースファイルとレンダリングされたウェブの場所
GitLab、GitLab Runner、Omnibus GitLab、Chartsのドキュメントは、https://docs.gitlab.com。 GitLabのドキュメントは、/help
GitLabインスタンスのドメイン上の /help
アプリケーション内部でも公開されています/help
。 では /help
、現在のエディションとバージョンのヘルプのみが含まれています。 他のバージョンのヘルプは、https://docs.gitlab.com/archives/。
ドキュメントのソースは、各 GitLab アプリケーションのコードベース内の以下のリポジトリに存在します:
プロジェクト | パス |
---|---|
GitLab | /doc
|
GitLab Runner | /docs
|
オムニバス GitLab | /doc
|
チャート | /doc
|
ドキュメンテーションイシューとマージリクエストはそれぞれのリポジトリの一部であり、すべてDocumentation
というラベルがついています。
ブランチのネーミング
GitLabのメインプロジェクトのCIパイプラインは、貢献の種類にマッチしたジョブだけを自動的に実行するように設定されています。 貢献がドキュメントの変更だけを含む場合、ドキュメント関連のジョブだけが実行され、パイプラインはコードの貢献よりもずっと速く完了します。
ドキュメントのみの変更をRunner、Omnibus、Chartに提出する場合、高速パイプラインは自動的に決定されません。 代わりに、以下のガイドを使ってドキュメントのみのマージリクエスト用のブランチを作成してください:
Branch name | 有効な例 |
---|---|
まずはdocs/
| docs/update-api-issues
|
まずはdocs-
| docs-update-api-issues
|
終了-docs
| 123-update-api-issues-docs
|
ドキュメントへの貢献者
GitLabドキュメントへの貢献者は、GitLabコミュニティ全体から歓迎されています。
GitLabのドキュメントが最新であることを保証するために、すべての機能の変更、つまり機能の外観、使い方、管理に影響を与える開発者には特別なプロセスと責任があります。
例えば、GitLabやサードパーティツールとGitLabですでに可能なユースケースを達成する方法について新しいドキュメントを追加するなどです。
マークダウンとスタイル
GitLab docsはMarkdownレンダリングエンジンとしてGitLab Kramdownを使用しています。 Kramdownの完全なリファレンスはGitLab Markdown Guideをご覧ください。
ドキュメント・スタイル・ガイドを遵守してください。 スタイル標準がない場合は、マージリクエストで提案してください。
フォルダ構造とファイル
ドキュメンテーション・スタイル・ガイド」の「構造」のセクションを参照してください。
メタデータ
追加のディレクティブや有用な情報を提供するために、それぞれの製品のドキュメントページの先頭にYAMLフォーマットのメタデータを追加します (YAMLフロントマター)。 すべての値は文字列として扱われ、docsのWebサイトでのみ使用されます。
ステージとグループのメタデータ
各ページには、そのページが属するステージやグループに関連するメタデータと、以下に説明するような情報ブロックがあるのが理想的です:
-
stage
ページのコンテンツの大部分が属するステージ。 -
group
ページのコンテンツの大部分が属するグループ。 -
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
例えば、以下のメタデータは、主に監査イベント機能に関連する製品ドキュメント・ページの冒頭にあります:
---
stage: Monitor
group: APM
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
---
ページタイプのメタデータ
もともとこのエピックで説明したように、各ページはtype
メタデータを持つべきです。メタデータは以下のうちの1つ以上です:
-
index
: 索引/概要ページ。 他のページへのリストとして機能します。 必ずしもそのページがindex.md
という名前でなければならないというわけではありません。例ページ。 -
concepts
製品を使用する前に知っておくべきこと。 例えば、アイデアを抽象化する、意味や利益を説明する、タスクの理解をサポートする、など。 なぜXが重要なのか」など、背景情報を得るために読まれます。例ページ。 -
howto
具体的な使用例の説明。例ページ。 -
tutorial
例ページ。 -
reference
具体的な設定や、あまり説明のない事実など、詳細な情報を得るために読まれるPages。例ページ。
リダイレクション・メタデータ
ページが別の場所に移動された場合、以下のメタデータを追加する必要があります:
-
redirect_to
: 移動したページの訪問者をリダイレクトする場所の相対パスとファイル名 (.md
拡張子付き)。詳しくはこちら。 -
disqus_identifier
Disqusコメントシステムの識別子。 新しいURLに移動されたページのコメントを保持するために使用されます。 詳細はこちら。
コメント・メタデータ
docs のウェブサイトでは、デフォルトでコメント (Disqus が提供) が有効になっています。 (インデックスページなどで) コメントを無効にしたい場合は、false
に設定してください:
---
comments: false
---
追加ページのメタデータ
各ページは追加の(オプションの)メタデータを持つことができ(default.htmlNanocレイアウトで設定)、定義されている場合は、ページの上部に表示されます:
-
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
にreading_time
設定reading_time
します。 これは、簡単なアルゴリズムを使って、単語数に基づいて読書時間を計算します。
ドキュメントの場所の変更
ドキュメントの場所を変更するには、ユーザーがGitLabインスタンスドメイン/help
のコンテンツにアクセスする場合でも、https://docs.gitlab.comのコンテンツにアクセスする場合でも、新しいdocページにシームレスにアクセスできるようにするための特別な手順が必要です。(移動が必要かどうかなど)プロセス中に質問がある場合は必ずテクニカルライターを割り当て、マージする前にテクニカルライターがこの変更をレビューするようにしてください。
ドキュメントの場所を変更する必要がある場合は、古いドキュメントを削除せずに、その内容をすべて以下のように置き換えてください:
---
redirect_to: '../path/to/file/index.md'
---
This document was moved to [another location](../path/to/file/index.md).
../path/to/file/index.md
は通常、古いドキュメントへの相対パスです。
redirect_to
変数は、完全 URL と相対 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
に移動する場合、手順は次のようになります:
-
doc/workflow/lfs/index.md
にコピーします。doc/administration/lfs.md
-
doc/workflow/lfs/index.md
の内部を置き換えてください:--- redirect_to: '../../administration/lfs.md' --- This document was moved to [another location](../../administration/lfs.md).
-
古い場所を検索し、新しい場所に置き換えます。すばやく検索するには、ファイルを変更したリポジトリの
git grep
を使用します:git grep -n "workflow/lfs/lfs_administration" git grep -n "lfs/lfs_administration"
注意すべきこと
- インラインドキュメントも使っているので、ドキュメントそのものを除けば、ドキュメントはGitLabのビュー (
app/
) でも参照されるかもしれません。/help
にアクセスしたときにレンダリングされますし、テストスイート (spec/
) でも参照されることがあります。これらのパスでドキュメントへの参照を探し、更新する必要があります。 - 上記の
git grep
コマンドは、実行したディレクトリ内のworkflow/lfs/lfs_administration
とlfs/lfs_administration
を再帰的に検索し、そのファイルと、そのファイルについて言及されている行を表示します。 なぜ2つのgrepを使うのかと聞かれるかもしれません。ドキュメントへのリンクには相対パスを使用するため、より深いパスを検索すると便利な場合があります。 - ドキュメントがGitLabのビルトインヘルプページにリンクされている場合は、
*.md
拡張子は使われません。そのため、git grep
では省略しています。 - MRの説明テンプレート「Change documentation location」のチェックリストを使用してください。
Disqusコメント付きページのリダイレクト
移転先のドキュメントページにすでにDisqusコメントがある場合、Disqusスレッドを維持する必要があります。
Disqusはページごとに識別子を使用し、https://docs.gitlab.comの場合、ページ識別子はページURLとなるように設定されています。 そのため、ドキュメントの場所を変更した場合、同じDisqus識別子として古いURLを保持する必要があります。
そのためには、古いURLを値として、変数disqus_identifier
をフロントマターに追加します。 例えば、https://docs.gitlab.com/my-old-location/README.html
で利用可能なドキュメントを新しい場所、https://docs.gitlab.com/my-new-location/index.html
に移動したとします。
新しい文書のフロント・マターに以下を追加します:
---
disqus_identifier: 'https://docs.gitlab.com/my-old-location/README.html'
---
注:index.html
またはREADME.html
の場合でも、disqus_identifier
のURLにファイル名を含める必要があります。
GitLab ドキュメントのマージリクエスト
作業を始める前に、上記の入門編「docsに貢献する」とドキュメントのワークフローを読んでください。
- 現在のマージリクエスト記述テンプレートを使用します。
- MR
Documentation
にラベルを付けます(GitLab チームメンバーなど、developer
にアクセスできる人だけができます)。 - 以下の注釈に従って、正しいマイルストーンを割り当ててください(GitLabチームメンバーなど、
developer
にアクセスできる人のみが行うことができます)。
文書がマージされるのは、それが既存の内容を改善するものであり、テンプレートとスタイル標準に従う誠実な努力を示すものであり、正確であると考えられる場合です。
ドクターをさらに良くするためのさらなるニーズは、フォローアップのMRやイシューで即座に対応すべきです。
~"Pick into X.Y"
を使って、正しいリリースにマージしてください。 リリースマネージャの作業が増えるので、できるだけ過去のリリースを選ぶのは避けてください。GitLab/help
すべてのGitLabインスタンスにはドキュメントが含まれており、/help
(https://gitlab.example.com/help
) にあります。例えば、https://gitlab.com/help。
https://docs.gitlab.com 上でオンラインで利用可能なドキュメントは、GitLab、Omnibus、Runner のmaster
ブランチから 4 時間ごとにデプロイされます。したがって、マージリクエストがマージされると、その日のうちにオンラインで利用可能になります(/help
)。ただし、MR に割り当てられたマイルストーン内で出荷されます。
例えば、あなたのマージリクエストのマイルストーンが2018-09-22にリリースされる11.3に設定されているとします。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/ ではマージされたその日に利用できるようになります。
リンク/help
新しい機能をビルドするとき、アプリケーションである GitLab からドキュメントをリンクする必要があるかもしれません。 これは通常、help_page_path
ヘルパーメソッドの助けを借りてapp/views/
ディレクトリ内部のファイルで行います。
最も単純な形では、/help
ページへのリンクを生成する HAML コードは次のようになります:
= link_to 'Help page', help_page_path('user/permissions')
help_page_path
には、リンクしたい文書へのパスを以下の規則で記述します:
- GitLab リポジトリの
doc/
ディレクトリからの相対パスです。 -
.md
の拡張子は省略可能です。 - スラッシュ (
/
) で終わってはいけません。
以下は、文脈に応じて使用すべき特別なケースです。 以下の1つ以上を組み合わせることができます:
-
アンカーリンクへのリンク。
help_page_path
メソッドの一部としてanchor
を使用します:= link_to 'Help page', help_page_path('user/permissions', anchor: 'anchor-link')
-
リンクは新しいタブで開きます。これはデフォルトの動作です:
= link_to 'Help page', help_page_path('user/permissions'), target: '_blank'
-
サークルアイコンへのリンク。通常、チェックボックスの近くなど、長い説明を使用できない設定で使用します。 基本的にどのようなフォントの素晴らしいアイコンでも使用できますが、
question-circle
:= link_to icon('question-circle'), help_page_path('user/permissions')
-
ボタンリンクを使用することで、テキストが他のページレイアウトの文脈から外れてしまうような場合に便利です:
= link_to 'Help page', help_page_path('user/permissions'), class: 'btn btn-info'
-
テキストのインラインでリンクを使用します。
Description to #{link_to 'Help page', help_page_path('user/permissions')}.
-
文末にピリオドを追加します。ピリオドをリンクの一部にしたくない場合に便利です:
= succeed '.' do Learn more in the = link_to 'Help page', help_page_path('user/permissions')
GitLab/help
テスト
いくつかのRSpecテストは、GitLabドキュメントが正しくレンダリングされ、正しく動作することを確認するために実行されます。 特に、メインのdocsランディングページは、/help
から正しく動作します。例えば、GitLab.com の/help
.
ドキュメント・サイト・アーキテクチャ
https://docs.gitlab.com 、どのようにサイトを構築しデプロイしているのか、また使用されているすべてのアセットとライブラリを確認するには、Docsサイトアーキテクチャページをご覧ください。
グローバルナビゲーション
左側ナビゲーションメニューの構築と更新方法については、グローバルナビゲーションdocをご覧ください。
変更をライブでプレビュー
ライブプレビューは現在、以下のプロジェクトで有効になっています:
マージリクエストにdocsの変更がある場合、手動review-docs-deploy
ジョブを使用して、マージリクエストのdocsレビューアプリをデプロイすることができます。 実行するには少なくともメンテナー権限が必要です。
review-docs-deploy*
のジョブは以下の通りです:
-
gitlab-docs
プロジェクト内に、docs-preview-$DOCS_GITLAB_REPO_SUFFIX-$CI_MERGE_REQUEST_IID
というスキームにちなんだ新しいブランチを作成します。DOCS_GITLAB_REPO_SUFFIX
は各プロダクトのサフィックスで、例えば、ee
は EE、omnibus
は Omnibus GitLab など、CI_MERGE_REQUEST_IID
はそれぞれのマージリクエストの ID です。 - クロスプロジェクトパイプラインをトリガーし、変更を加えてドキュメントサイトを構築します。
レビューアプリの URL が 404 を返した場合、サイトがまだデプロイされていないか、リモートパイプラインで何か問題が発生したことを意味します。 数分待てばオンラインに表示されるはずです。そうでなければ、マージリクエストのジョブ出力のリンクからリモートパイプラインのステータスを確認できます。パイプラインが失敗したり、スタックした場合は、#docs
のチャットチャンネルに連絡してください。
レビューアプリのトラブルシューティング
レビューアプリのURLが404を返した場合は、以下の手順に従ってデバッグしてください:
- マージリクエストウィジェットのURLをたどりましたか?もしそうなら、リンクがジョブ出力のものと同じかどうか確認してください。
-
ジョブの出力から URL をたどりましたか?もしそうなら、サイトがまだデプロイされていないか、リモートパイプラインに何か問題があったということです。 数分待てばオンラインになるはずです。そうでなければ、ジョブの出力にあるリンクからリモートパイプラインのステータスを確認できます。パイプラインが失敗したり、スタックした場合は、
#docs
チャットチャンネルに連絡してください。
技術的側面
詳細についてお知りになりたい方は、こちらをご覧ください:
- マージリクエストで
review-docs-deploy
ジョブを手動で実行します。 - このジョブは、
scripts/trigger-build-docs
スクリプトをdeploy
フラグ付きで実行します:- ブランチ名を入力し、以下を適用します:
-
docs-preview-
のプレフィックスが追加されます。 - プロダクトスラッグは、レビューアプリがどのプロジェクトから生まれたかを知るために使用されます。
-
gitlab-docs
ブランチ名でマージリクエストの元がわかるように、マージリクエストの番号が追加されます。
-
- リモートブランチが存在しない場合は、そのブランチが作成されます (つまり、手動ジョブは何度でも再実行でき、このステップはスキップされます)。
- docsプロジェクトで新しいクロスプロジェクトパイプラインが起動します。
- プレビューURLはジョブ出力とマージリクエストウィジェットの両方に表示されます。 リモートパイプラインへのリンクも取得できます。
- ブランチ名を入力し、以下を適用します:
- docsプロジェクトでは、パイプラインが作成され、ビルド時間を短縮するためにテストジョブをスキップします。
- docsサイトが構築されると、HTMLファイルはアーティファクトとしてアップロードされます。
- docsプロジェクトにのみ関連付けられた特定のRunnerは、アーティファクトをダウンロードするレビューアプリジョブを実行し、
rsync
、NGINXがそれらを提供する場所にファイルを転送するために使用します。
特に以下のGitLabの機能が使用されています:
テスト
私たちはドキュメントをコードとして扱っているため、ドキュメントの標準と品質を維持するためにCIパイプラインでテストを使用しています。 現在のテストは、新しいドキュメントや変更されたドキュメントのマージリクエストが提出されたときにCIジョブで実行されます:
-
docs lint
ドキュメント自体の内容に関するいくつかのテストを実行します:-
lint-doc.sh
スクリプトは以下のチェックとリンターを実行します: - ナノックのテスト
-
internal_links
はすべての内部リンク (例:[link](../index.md)
) が有効かどうかをチェックします。 -
internal_anchors
は、すべての内部アンカー (例:[link](../index.md#internal_anchor)
) が有効であることをチェックします。
-
-
テストの実行
変更をローカルでプレビューするだけでなく、すべてのlintチェックとNanocテストをローカルで実行することもできます。
ナノックテスト
Nanocテストをローカルで実行する場合:
-
gitlab-docs
ディレクトリに移動します。 -
以下を実行する:
# Check for broken internal links bundle exec nanoc check internal_links # Check for broken external links (might take a lot of time to complete). # This test is set to be allowed to fail and is run only in the gitlab-docs project CI bundle exec nanoc check internal_anchors
糸くずチェック
Lintチェックはlint-doc.sh
スクリプトによって実行され、以下のように実行できます:
-
gitlab
ディレクトリに移動します。 -
以下を実行する:
MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh
MD_DOC_PATH
は、lintチェックを実行したいファイルまたはディレクトリを指します。 完全に省略すると、デフォルトでdoc/
ディレクトリになります。 出力は以下のようになるはずです:
=> Linting documents at path /path/to/gitlab as <user>...
=> Checking for cURL short options...
=> Checking for CHANGELOG.md duplicate entries...
=> Checking /path/to/gitlab/doc for executable permissions...
=> Checking for new README.md files...
=> Linting markdown style...
=> Linting prose...
✔ 0 errors, 0 warnings and 0 suggestions in 1 file.
✔ Linting passed
このためには、あなたのマシンに必要なlintツールがインストールされているか、Dockerがインストールされている必要があります。
地元のリンター
ドキュメント・スタイル・ガイドラインを遵守し、ドキュメントに追加する内容を改善するために、ドキュメント・リンターをインストールし、コード・エディターとインテグレーションしてください。
GitLabでは、主に以下のものを使っています:
マークダウンリント
markdownlintはMarkdown構文が特定のルールに従っているかチェックし、docs-lint
テストで使用されます。
GitLabドキュメンテーションのためにMarkdown構文を選択する際にどのような選択をしなければならないかについて、私たちのドキュメンテーションスタイルガイドとMarkdownガイドが詳しく説明しています。 このツールは、これらのガイドラインからの逸脱をキャッチするのに役立ちます。
markdownlintの設定は以下のプロジェクトにあります:
この設定はビルドパイプラインでも使用されます。
markdownlintが使えます:
ヴェール
Valeは、英語の文法・スタイル・語法リンターです。 Valeの設定は、プロジェクトのルートディレクトリにある.vale.ini
ファイルに保存されます。
Vale は、いくつかのタイプのチェックを拡張したカスタムテストの作成をサポートしています。これらのテストは、プロジェクトの documentation ディレクトリ内の.linting/vale/styles/gitlab
ディレクトリに保存されます。
ベイルのコンフィギュレーションは以下のプロジェクトにあります:
この設定はビルドパイプラインでも使用されます。
ヴェイルは使えます:
リンターの取り付け
最低限、markdownlintと Valeをインストールして、ビルドパイプラインで実行されるチェックと一致させてください:
-
markdownlint-cli
をインストールしてください:-
npm
:npm install -g markdownlint-cli
-
yarn
:yarn global add markdownlint-cli
ドキュメントのlintingDockerイメージで現在使用されている
markdownlint-cli
のバージョンをインストールすることをお勧めします。
-
-
vale
をインストールします。例えば、brew
for MacOS を使ってインストールするには、次のように実行します:brew install vale
ドキュメントのlintingDockerイメージで現在使用されているバージョンのValeをインストールすることをお勧めします。
markdownlintとValeをコマンドラインで使うだけでなく、これらのツールをコードエディターにインテグレーションすることもできます。
エディタの設定
エディタ内でmarkdownlintを設定するには、必要に応じて以下のいずれかをインストールしてください:
エディタ内でValeを設定するには、適切な以下のいずれかをインストールしてください:
- Sublime Text
SublimeLinter-contrib-vale
プラグイン - Visual Studio Code
testthedocs.vale
拡張機能
ベイル・サーバーは使っていません。
ベールテストの無効化
ドキュメントの任意の部分について、特定のVale lintingルールまたはすべてのVale lintingルールを無効にすることができます:
- 特定のルールを無効にするには、
<!-- vale gitlab.rulename = NO -->
タグをテキストの前に追加し、<!-- vale gitlab.rulename = YES -->
タグをテキストの後に追加します。rulename
はGitLab stylesディレクトリにあるテストのファイル名に置き換えてください。 - すべてのヴェイル・リンティング・ルールを無効にするには、テキストの前に
<!-- vale off -->
タグを、テキストの後に<!-- vale on -->
タグを追加します。
可能な限り、問題のあるルールと行だけを除外してください。 リスト項目などの場合、イシュー#175が解決するまで、リスト全体のリンティングを無効にする必要があるかもしれません。
詳しくはヴァーレのドキュメントをご覧ください。
デンジャーボット
GitLabはコードレビューのいくつかの要素にDangerを使用しています。マージリクエストにおけるdocsの変更のために、/doc
のファイルが変更されるたびに、Danger Botはドキュメントプロセスに関するさらなる指示をコメントに残します。これはGitLabリポジトリの/danger/documentation/のDangerfile
で設定します。