Quarkusドキュメントの寄稿方法
QuarkusのWebサイトポータルでコンテンツが正常にレンダリングされるように、推奨されるコンテンツタイプ、ステップ、ワークフロー、スタイルガイダンスを使用して、ドキュメントに貢献します。
Quarkusのドキュメントには、 AsciiDoc のマークアップが使用されています。
要件
-
AsciiDoc の構文の強調表示とプレビューを提供するエディターまたは IDE がある。(ネイティブまたはプラグイン)
-
以下の Quarkus コントリビューターリソースを確認した。
-
Quarkus "貢献" ガイドの ドキュメント セクション。
-
必要な構文、推奨されるスタイル、およびその他の規則については、Quarkus のスタイルとコンテンツのガイドライン を参照してください。
-
-
AsciiDoc 構文リファレンス がある。
Quarkus docsのソースファイルの場所を確認する。
-
AsciiDocファイルが、Quarkus GitHub リポジトリー. の
docsモジュール内のsrc/main/asciidocディレクトリーにある。 -
Quarkus ドキュメントテンプレートは、Quarkus GitHub リポジトリー の
docsモジュール内のsrc/main/asciidoc/_templatesディレクトリーにあります。 -
設定ドキュメントは、Javaソースファイル内のJavaDocコメントから生成されます。
-
JavaやYAMLなどのソースファイルをAsciiDocのファイルから 参照 することも可能です。
-
Quarkusのドキュメント メニューページは、doc indexページとも呼ばれ、 quarkusio.github.io リポジトリにソースがあります。
QuarkusのコンテンツをAsciiDocで作成
Quarkusドキュメントホームページ にコンテンツが正しく表示されるようにするには、次のステップを使用します:
-
投稿するコンテンツに最適な Diataxis のコンテンツタイプを決めましょう。
決定するには、Quarkus ドキュメントについてページの タイトルと見出し にあるコンテンツタイプの説明を参照してください。 -
src/main/asciidoc/_templatesディレクトリに移動し、選択したコンテンツタイプに対応するテンプレートのコピーを作成します。必ず、以下のようにしてください:-
ファイル名の構文は
<category> -<titlekeyword> -<titlekeyword> .adoc。たとえば、security-basic-authentication.adocです。 -
必要に応じて、ダイアタキシスの種類 (概念、ハウツー、リファレンス、チュートリアル) をファイル名に含めます。 たとえば、
telemetry-micrometer.adocはリファレンスであり、telemetry-micrometer-tutorial.adocはチュートリアルです。 -
quarkusリポジトリのdocs/src/main/asciidocフォルダに保存してください。
-
-
次の例に示すように、Web サイトポータルとドキュメントのホームページでコンテンツが正しく表示されるように、最低限必要なヘッダー情報を設定します。
[id="security-basic-authentication"] (1) = Secure a Quarkus application with basic authentication (2) include::_attributes.adoc[] (3) :diataxis-type: howto (4) :categories: security,web (5) (6)1 id値をファイル名と同じ (拡張子なし) に設定します。2 各コンテンツタイプに適したタイトルの作成方法については、「Quarkusスタイルコンテンツガイドライン」ページの タイトルと見出し を参照してください。 3 属性が解決され、目次が生成されるようにするには、 _attributes.adocinclude が必要です。4 concept、howto、reference、またはtutorialから diataxis のタイプを指定します。5 Quarkusドキュメントのホームページ でコンテンツが検索できるように、少なくとも1つのカテゴリーを設定してください。Quarkusのカテゴリのリストについては、「Quarkusスタイル・コンテンツガイドライン」ページの ドキュメントの属性と変数 を参照してください。 6 すべてのドキュメント属性の後、要約の前に空白行を挿入します。 ドキュメント ID とタイトル、属性 include (
include::_attributes.adoc[])、およびその他のドキュメント属性の宣言 (:attribute:) の間に空白行がないことを確認します。 -
ガイドの目的を説明する要約を追加します。
Quarkusガイド のホームページに自動的に表示されるため、要約の最初の文は、コンテンツの価値と何らかの利益を27単語以内で説明する必要があります。また、要約の前後で改行する必要があります。
ヘッダーの最小要件の詳細は、「Quarkus スタイルコンテンツガイドライン」ページの ドキュメント構造 を参照してください。
前提条件セクションの追加
方法やチュートリアルのトピックの場合は、要約の直後に前提条件のセクションを含めます。 前提条件を宣言すると、方法のコンテンツとチュートリアルコンテンツの両方がどこから始まるのかが明確になります。 知識のあるユーザーにとっては明確なことであって、前提条件は含めてください。
.Prerequisites (1)
:prerequisites-time: 30 minutes (2)
include::{includes}/prerequisites.adoc[] (3)
* <an additional prerequisite> (4)| 1 | 前提条件のセクション見出し |
| 2 | オプション: 前提条件を変更する属性 |
| 3 | prerequisites.adoc ファイルの include ステートメント |
| 4 | オプション: 属性でカバーされていない追加の前提条件 |
デフォルトでは、 include::./_includes/prerequisites.adoc[] は次の asciidoc を挿入します。
To complete this guide, you need:
* Roughly 15 minutes
* An IDE
* JDK 17+ installed with `JAVA_HOME` configured appropriately
* Apache Maven {maven-version}
* Optionally the xref:cli-tooling.adoc[Quarkus CLI] if you want to use it
* Optionally Mandrel or GraalVM installed and xref:building-native-image.adoc#configuring-graalvm[configured appropriately] if you want to build a native executable (or Docker if you use a native container build)オプションで、 include::./_includes/prerequisites.adoc[] マクロ の前の行に次の属性を挿入することで、デフォルトの前提条件を追加、削除、または変更できます。
-
{prerequisites-time} :<number of minutes> ` はデフォルト値の 15 分を上書きします。たとえば、 `{prerequisites-time}: 30は*約 30 分を追加します。 -
{prerequisites-no-maven}は* Apache Maven <maven version>を削除します。 -
{prerequisites-docker}は*動作するコンテナランタイム(Docker, Podman)を追加します。 -
{prerequisites-docker-compose}はDocker および Docker Compose または Podman、および Docker Composeを追加します。 -
{prerequisites-no-cli}は、*CLI を使用する場合は Quarkus CLI を使用するを削除します。 -
{prerequisites-no-graalvm}または{prerequisites-graalvm-mandatory}は*ネイティブ実行可能ファイルをビルドする場合、MandrelまたはGraalVM（あるいはネイティブなコンテナビルドを使用する場合はDocker）をインストールし、 適切に設定しているを削除します。 -
{prerequisites-graalvm-mandatory}は、MandrelまたはGraalVMがインストールされ、 適切に設定されていること を追加します。
これらの属性の詳細は、 docs/src/main/asciidoc/_includes/prerequisites.adoc ファイルの内容を確認してください。
既存のQuarkus AsciiDocソースファイルの削除とリダイレクト
コンテンツの進化に伴い、既存のQuarkusコンテンツを1つまたは複数のコンテンツタイプに再編成し、既存のAsciiDocソースファイルを破棄したい場合があります。
公開済みの Quarkus AsciiDoc ソースファイルを廃止または名前変更する場合は、再構築によって既存のブックマークや元のコンテンツへのリンクが壊れないように注意してください。 次の手順に従って、Quarkus.io Web サイト GitHub リポジトリーで URL リダイレクトを設定します。
-
quarkusio/quarkusio.github.ioリポジトリーに切り替えて、_redirects/guidesフォルダーを開きます。 -
破棄したい元のAsciiDocのソースファイル名と一致するファイル名のリダイレクトファイルをMarkdown形式で作成します。
-
Markdownリダイレクトファイルに、以下の内容を追加します:
--- permalink: /guides/<original_asciidoc_filename>/index.html (1) newUrl: /guides/<new_asciidoc_filename> (2) ---以下の場合:
1 廃止する元の AsciiDoc ソースファイルの名前 ( .adocファイル拡張子なし)。2 リダイレクト先の AsciiDoc ソースファイルの名前 ( .adocファイル拡張子なし)。
| 元のAsciiDocソースファイル名 | リダイレクト先となるファイル名 | リダイレクトファイル | プルリクエストの例 |
|---|---|---|---|
|
|
アンカーを使用したファイル内およびファイル間のコンテンツの相互参照
アンカー (ID とも呼ばれます) は、セクションタイトル、個別の見出し、段落、イメージ、区切られたブロック、インラインフレーズなど、ドキュメント内のほぼどこにでも定義できます。
これらのアンカーのコールアウト関数は、ローカル ID を呼び出すか、別のファイルの ID を呼び出すかによって異なりますが、アンカー ID の作成は同じままです。
アンカー ID の作成
参照する新しいファイルまたはセクションの ID を作成するには、次のようにアンカー ID を挿入します。
-
小文字を使用してください。
-
各単語をダッシュ文字で区切ります。
-
ID を二重の角括弧で囲みます。
このセクションでは、デモンストレーションの目的でレベル 2 の見出しの上に作成されたアンカーを使用します。
[[title-heading]]
== Title heading同じファイル内のアンカー ID の呼び出し
同じファイルに作成されたアンカーを呼び出すには、 <<>> xref マクロにアンカーIDを挿入してください。
<<title-heading>>このマクロは、アンカーされた見出し、セクション、または表から自動的に取得された名前を指定して URL を作成します。
<<Title heading>> のように、
逐語的な見出しやセクションの説明に <<> 形式を使用しないでください。
|
URL にデフォルト以外のキャプションを指定する場合は、アンカー ID と希望の名前を空白なしで , で区切って指定します。
<<title-heading,Title heading description that fits the context of your content>>別のファイルからアンカー ID を呼び出す
別のファイルで作成されたアンカーを呼び出すには、アンカーを xref マクロに挿入し、ホスティングファイルの完全な名前と目的のアンカー ID を指定します。
xref:<other-file-name>.adoc#title-heading[Title heading]この例を分解すると、 xref マクロを使用して別のファイルを参照しています (xref:<name-of-the-file>.adoc[人間が読めるラベル]) を作成し、ファイル名の直後に対象セクションのアンカー ID (#title-heading) を挿入します。
推奨されるパス属性を含む相互参照の記述に関する詳細なガイドラインについては、相互参照 を参照してください。
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 ブランチに対して、https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork[プルリクエストの作成] を行い、自身の リポジトリーのフォーク から Quarkus のコアドキュメントに変更案を提出します。
コードとドキュメントのレビューには、さまざまな参加者 (重複する場合もある) がいます。 共同レビューを簡素化するには、ドキュメントへの変更を別々の PR に分離するか、PR の目的が 1 つに絞られていることを確認します。例:
-
エクステンションの設定オプションを追加し、変更を説明するために関連資料 (ハウツー、リファレンス) を更新する単一の PR を作成します。
-
ドキュメントのグループに関連する変更に対して単一の PR を作成します。例: 用語の使用法を修正したり、繰り返し発生するエラーを修正したり、共通のコンテンツを共有ファイルに移動したりします。
-
広範囲なコード変更とドキュメント変更がある場合、ドキュメント変更のために別のPRを作成し、Issueの説明にその関係性を含めてください。
GitHub は、ドキュメントファイルへの変更を含むプルリクエストに area/documentation ラベルを自動的に追加します。
プルリクエストの管理の詳細は、Quarkus でコミットする方向けの情報 を参照してください。
QuarkusのWebサイトでdocの変更点をプレビューする
PRが main にマージされ、ブランチが Quarkus.io ウェブサイトのリポジトリと同期されると、Quarkusサイトの Main branch (SNAPSHOT) ドキュメントページで、結果のビルド出力をプレビューすることができます。
|
|
