Quarkusドキュメントの寄稿方法
推奨される手順、ワークフロー、スタイルガイダンスを使用して、Quarkusウェブサイトのポータルでコンテンツが正常にレンダリングされるようにし、ドキュメントを寄稿します。
前提条件
Quarkusのドキュメントには、 AsciiDoc のマークアップが使用されています。
以下の資料を近くに置いておくことをお勧めします。
-
組込機能またはプラグインを使用して、AsciiDocの構文の強調表示とプレビューを提供するエディターまたは IDE。
-
必要な構文やその他の規約のリファレンスとして Quarkus スタイル・コンテンツガイドライン
Quarkus docsのソースファイルの場所を確認する
-
AsciiDocファイルは、 Quarkus GitHubリポジトリ の
docsモジュール内のsrc/main/asciidocディレクトリにあります。 -
設定ドキュメントは、Javaソースファイル内のJavaDocコメントから生成されます。
-
JavaやYAMLなどのソースファイルをAsciiDocのファイルから 参照 することも可能です。
-
Quarkusのドキュメント メニューページは、doc indexページとも呼ばれ、 quarkusio.github.io リポジトリにソースがあります。
QuarkusのコンテンツをAsciiDocで作成
Quarkusドキュメントホームページ にコンテンツが正しく表示されるようにするには、次のステップを使用します：
-
投稿するコンテンツに最適なコンテンツタイプを決めます。
判断材料として、「Quarkusのドキュメントについて」ページの タイトルと見出し のコンテンツタイプの説明をご覧ください。 -
src/main/asciidoc/_templatesディレクトリに移動し、選択したコンテンツタイプに対応するテンプレートのコピーを作成します。必ず、以下のようにしてください:-
ファイル名の構文は、<category>-<titlekeyword>-<titlekeyword>-<content-type>.adoc` を使用してください。例えば、
security-basic-authentication-tutorial.adocです。 -
quarkusリポジトリのdocs/src/main/asciidocフォルダに保存してください。
-
-
以下の例のように、最低限必要なヘッダー情報を設定します：
[id="security-basic-authentication-howto"] (1) = Secure a Quarkus application with basic authentication (2) include::_attributes.adoc[] (3) :categories: security,web (4)1 idの値は、ファイル名と同じで、拡張子を除いたものに設定してください。ファイル名が長すぎる場合は、これを短くすることができます。2 各コンテンツタイプに適したタイトルの作成方法については、「Quarkusスタイル・コンテンツガイドライン」ページの タイトルと見出し を参照してください。 3 _attributes.adocインクルードは、属性が解決され、目次が生成され、コンテンツがウェブサイトポータルにレンダリングされるようにするために必要です。4 Quarkusドキュメントのホームページ でコンテンツが検索できるように、少なくとも1つのカテゴリーを設定してください。Quarkusのカテゴリのリストについては、「Quarkusスタイル・コンテンツガイドライン」ページの ドキュメントの属性と変数 を参照してください。 :categories:行の後まではヘッダー部に改行が ないようにして下さい。 -
ガイドの目的を説明するための要約を追加する。
Quarkusガイド のホームページに自動的に表示されるため、要約の最初の文は、コンテンツの価値と何らかの利益を27単語以内で説明する必要があります。また、要約の前後で改行する必要があります。
ヘッダーの最小要件の詳細については、「Quarkusスタイル・コンテンツガイドライン」ページの ドキュメント構造 を参照してください。
既存のQuarkus AsciiDocソースファイルの削除とリダイレクト
コンテンツの進化に伴い、既存のQuarkusコンテンツを1つまたは複数のコンテンツタイプに再編成し、既存のAsciiDocソースファイルを破棄したい場合があります。
If you are retiring or renaming a published Quarkus AsciiDoc source file, ensure that the restructure does not break existing bookmarks and links to original content. Configure a URL redirect in the Quarkus.io Website GitHub repository by using the following steps:
-
Switch to the quarkusio/quarkusio.github.io repository, and open the
_redirects/guidesfolder. -
破棄したい元のAsciiDocのソースファイル名と一致するファイル名のリダイレクトファイルをMarkdown形式で作成します。
-
Markdownリダイレクトファイルに、以下の内容を追加します:
--- permalink: /guides/<original_asciidoc_filename>/index.html (1) newUrl: /guides/<new_asciidoc_filename> (2) ---何処に
1 破棄したい元のAsciiDocソースファイル名があったか。 .adocファイル拡張子を除きます。2 リダイレクトしたいAsciiDocのソースファイル名があるか。 .adocのファイル拡張子は除きます。
| 元のAsciiDocソースファイル名 | リダイレクト先となるファイル名 | リダイレクトファイル | プルリクエストの例 |
|---|---|---|---|
|
|
Quarkusドキュメントのプレビューとビルド
Pull Request を送信する前に、以下のビルド方法のいずれかを使用して、AsciiDoc ソースの HTML 出力をプレビューしてください：
-
ちょっとしたドキュメントの変更であれば、IDEが提供するAsciiDocのシンタックスハイライトとプレビューを利用することができます。
-
生成された設定ドキュメントの大幅な変更や更新は、
docsモジュールをローカルでビルドし、以下のセクションで説明するように Vale linter を実行してください。
docs モジュールをローカルでビルド
以下は、Quarkusリポジトリにあるすべてのモジュール（テストモジュールを除く）をビルドし、 `999-SNAPSHOT`バージョンでローカルmavenリポジトリにインストールします：
./mvnw -DquicklyDocs-DquicklyDocs の実行は以下を生成します：
-
target/asciidoc/generated/config/ディレクトリに自動生成の設定プロパティを記述したAsciiDoc（adocファイル） -
docs/target/generated-docs/ディレクトリにAsciiDoc出力（htmlファイル）。 -
全ドキュメント個別のメタデータを含むYAML ( `docs/target/indexByFile.yaml `) とドキュメントタイプ別にグループ化したメタデータを含むYAML ( `target/indexByType.yaml `)。
-
ファイル別にメタデータのエラーをリストアップするYAMLファイル( `docs/target/errorsByFile.yaml `)と、エラーの種類別にメタデータのエラーをリストアップするYAMLファイル( `docs/target/errorsByType.yaml `)
変更をPRで提出し、レビューを受ける前に、結果の出力をレビューし、問題があれば修正を行ってください。
変更を加えると、特に docs モジュールを再構築して、生成された HTML を更新できます。
./mvnw -f docs clean install|
エクステンションの設定を更新する場合:
|
Valeによるドキュメント変更の性的解析
我々は Vale を使用して、英語版ドキュメントの文法、スタイル、単語の使用状況をチェックしています。独自のValeスタイルルールセットを作成し、コンテンツがQuarkusの推奨スタイルガイドラインに沿うようにしました。
|
コンテナ化されたVale
この方法では、動作するコンテナランタイム（Dockerまたは Podman ）が必要です。
docs モジュールには、JUnit 5 テストがあり、コンテナ内で Vale リンターを実行します（ Testcontainers を使用）。QuarkusドキュメントのメタデータとValeスタイルルールの両方が検証されます。
以下のいずれかの方法でテストを実行します：
./mvnw -f docs test -Dvale -DvaleLevel=suggestion (1)
./mvnw -f docs test -Dvale=git -DvaleLevel=warning (2)
./mvnw -f docs test -Dvale='doc-.*' -DvaleLevel=error (3)| 1 | docs モジュールの src/main/asciidoc ディレクトリにあるすべての *.adoc ファイルに対して Vale linter を実行します。結果には提案、警告、エラーが含まれます。 |
| 2 | docs モジュール内の変更された *.adoc ファイル ( git status )に対して Vale linter を実行します。結果には警告とエラーが含まれます。 |
| 3 | 正規表現（Java Pattern構文）に一致する *.adoc ファイルに対して、Vale linterを実行します。結果にはエラーが含まれます。 |
Vale CLIの使用
Vale CLI をインストールした場合、設定ファイルとスキャンするファイルのディレクトリまたはリストを指定する必要があります：
# Run from the Quarkus project root
vale --config=docs/.vale.ini --minAlertLevel=warning docs/src/main/asciidoc
# Run from within the docs directory
vale --minAlertLevel=warning src/main/asciidoc詳しくは、 Vale CLI Manual をご覧ください。
Vale IDE プラグイン
Vale IDEとの連携 には、Vale CLIがインストールされていることが必要です。
各 IDE 統合には、独自の設定要件があります。例えば、Visual Studio CodeのIDE拡張では、Vale CLIパスの定義が必要です：
"vale.valeCLI.path": "/path/to/vale"ドキュメント更新のためのプルリクエストの作成
Quarkus リポジトリーの main ブランチに対して、 プルリクエストの作成 を行い、自身の リポジトリーのフォーク から Quarkus のコアドキュメントに変更案を提出します。
Reviews for code and documentation have different (but overlapping) participants. To simplify collaborative review, either isolate changes to docs in their own PRs, or ensure that the PR has a single, focused purpose. For example:
-
エクステンションの設定オプションを追加し、変更を説明するために関連資料 (ハウツー、リファレンス) を更新する単一の PR を作成します。
-
Create a single PR for related changes to a group of documents, some examples: correcting the usage of a term, correcting a recurring error, or moving common content into a shared file.
-
広範囲なコード変更とドキュメント変更がある場合、ドキュメント変更のために別のPRを作成し、Issueの説明にその関係性を含めてください。
ドキュメントの変更を含むプルリクエストには、 area/documentation のラベルが自動的に追加されます。
QuarkusのWebサイトでdocの変更点をプレビューする
After your PR is merged to main and the branch is synchronized with the Quarkus.io website repository, you can preview the resulting build output on the Main branch (SNAPSHOT) documentation page of the Quarkus site.
|
|
