ドキュメントへのコントリビュート¶

私たちは Incus をできるだけ簡単に使えるようにしたいと考えています。ですので、Incus を使用するユーザーが必要とする（よくある使い方すべてをカバーし、典型的な質問に答えるような）情報を含んだドキュメントを提供を目指しています。

いろいろな方法でドキュメントにコントリビュートできます。あなたのコントリビュートを感謝します！

コントリビュートする典型的な方法は以下のとおりです。

コードにあなたがコントリビュートする新機能や機能改善についてのドキュメントを追加あるいは更新します。私たちはドキュメントの更新をレビューし、あなたのコードとともにマージします。
Incus を使っているときに感じた疑問点を明確にするようなドキュメントを追加あるいは更新します。それらの修正は Pull Request またはフォーラムのTutorialsセクションへの投稿で送ってください。新しいチュートリアルはドキュメントへ含める（リンク経由で参照あるいは実際のコンテンツをインクルード）ことを検討します。
ドキュメントの修正を依頼するために、GitHubでドキュメントに関するイシューを作成します。
質問や提案をフォーラムに投稿してください。私たちはイシューを評価し、適切にドキュメントを更新します。

ドキュメントのフレームワーク¶

Incus のドキュメントはSphinxでビルドされます。

ドキュメントはMarkdownとMySTの拡張で書かれています。構文のヘルプやガイドラインについては、ドキュメントチートシート (ソース)を参照してください。

構成に関しては、このドキュメントではDiátaxisアプローチを採用しています。

ドキュメントのビルド¶

ドキュメントをビルドするには、リポジトリのルートディレクトリーからmake docを実行します。このコマンドは必要なツールをインストールして、出力をdoc/html/ディレクトリーにレンダリングします。変更されたファイルのみを対象に（ツールを再インストールすることなく）ドキュメントを更新するには、make doc-incrementalを実行します。

Pull Request をオープンする前に、ドキュメントが警告なしでビルドできることを確認してください（警告はエラーとして扱われます）。ドキュメントをローカルでプレビューするには、make doc-serveを実行しhttp://localhost:8001をブラウザで開いてください。

Pull Request をオープンすると、ドキュメントのプレビュー出力が自動的にビルドされます。

ドキュメントの自動チェック¶

GitHub はドキュメントのスペル、リンク先が正しいか、Markdown ファイルのフォーマットが正しいか、差別用語を使用していないか、を自動的にチェックします。

ローカルでも以下のコマンドでこれらのチェックができます（してください！）。

スペルをチェックする：make doc-spellcheck
リンクの有効性をチェックする：make doc-linkcheck
Markdown のフォーマットをチェックする：make doc-lint
差別用語を使っていないかをチェックする：make doc-woke

上記を実行するためには、以下のものが必要です:

Python 3.8以降
venv pythonパッケージ
スペルチェック用にaspellツール
mdl markdown lintツール

ドキュメントの設定オプション¶

注釈

現在ドキュメントの設定オプションをコード内のコメントに移行中です。現時点では、一部の設定オプションはこのアプローチに沿っていません。

ドキュメントの設定オプションは Go コード内のコメントから抽出されます。コード内のgendoc:generateで始まるコメントを参照してください。

設定オプションを追加または変更する際は、それに必要なドキュメントのコメントを含めるようにしてください。

次にmake generate-configを実行してdoc/config_options.txtファイルを再生成してください。更新されたファイルはチェックインしてください。

ドキュメントでは、設定オプションのグループを表示するために、doc/config_options.txtの一部をインクルードしています。たとえば、コアのサーバーオプションをインクルードするには以下のようにします。

% Include content from [config_options.txt](config_options.txt)
```{include} config_options.txt
    :start-after: <!-- config group server-core start -->
    :end-before: <!-- config group server-core end -->
```

既存のグループに設定を追加した場合は、ドキュメントファイルを更新する必要はありません。新しいオプションは自動的に取り込まれます。新しいグループを追加した場合のみ、ドキュメントファイルにインクルードを追加する必要があります。