Quarkusドキュメントの寄稿方法
QuarkusのWebサイトポータルでコンテンツが正常にレンダリングされるように、推奨されるコンテンツタイプ、ステップ、ワークフロー、スタイルガイダンスを使用して、ドキュメントに貢献します。
Quarkusのドキュメントには、 AsciiDoc のマークアップが使用されています。
前提条件
-
You have an editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
-
You have reviewed the following Quarkus contributor resources:
-
The Documentation section of the Quarkus "Contributing" guide.
-
The Quarkus style and content guidelines for the required syntax, preferred style, and other conventions.
-
-
You have the AsciiDoc syntax reference nearby.
Quarkus docsのソースファイルの場所を確認する
-
AsciiDoc files are in the
src/main/asciidocdirectory within thedocsmodule of the Quarkus GitHub repository. -
The Quarkus doc templates are located in the
src/main/asciidoc/_templatesdirectory within thedocsmodule of the Quarkus GitHub repository. -
設定ドキュメントは、Javaソースファイル内のJavaDocコメントから生成されます。
-
JavaやYAMLなどのソースファイルをAsciiDocのファイルから 参照 することも可能です。
-
Quarkusのドキュメント メニューページは、doc indexページとも呼ばれ、 quarkusio.github.io リポジトリにソースがあります。
QuarkusのコンテンツをAsciiDocで作成
Quarkusドキュメントホームページ にコンテンツが正しく表示されるようにするには、次のステップを使用します:
-
投稿するコンテンツに最適な Diataxis のコンテンツタイプを決めましょう。
To help you decide, see the content type descriptions in Titles and headings on the "About Quarkus documentation" page. -
src/main/asciidoc/_templatesディレクトリに移動し、選択したコンテンツタイプに対応するテンプレートのコピーを作成します。必ず、以下のようにしてください:-
Use the filename syntax of`<category>-<titlekeyword>-<titlekeyword>.adoc`. For example,
security-basic-authentication.adoc. -
Include the diataxis type (concept, howto, reference, tutorial) in the file name if it makes sense to do so. For example,
telemetry-micrometer.adocis a reference, andtelemetry-micrometer-tutorial.adocis a tutorial. -
quarkusリポジトリのdocs/src/main/asciidocフォルダに保存してください。
-
-
Set the minimum required header information to ensure that the content renders correctly in the website portal and on the documentation home page, as outlined in the following example:
[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 Set the idvalue to be the same as the file name but without the extension.2 For information about how to create a good title for each content type, see Titles and headings on the "Quarkus style and content guidelines" page. 3 The _attributes.adocinclude is required to ensure that attributes get resolved and the table of contents is generated.4 Specify the diataxis type: concept,howto,reference, ortutorial.5 Set at least one category to ensure that the content is findable on the Quarkus documentation home page. For a list of Quarkus categories, see Document attributes and variables on the "Quarkus style and content guidelines" page. 6 Insert a blank line after all document attributes and before the abstract. Ensure there are no blank lines between the document id and title, the attribute include (
include::_attributes.adoc[]) and the declaration of other document attributes(:attribute:). -
Add an abstract that describes the purpose of the guide.
Quarkusガイド のホームページに自動的に表示されるため、要約の最初の文は、コンテンツの価値と何らかの利益を27単語以内で説明する必要があります。また、要約の前後で改行する必要があります。
For more information about the minimum header requirements, see Document structure on the "Quarkus style and content guidelines" page.
Add a prerequisites section
For how-to and tutorial topics, include a prerequisites section just after the abstract. Declaring prerequisites clarifies the starting place for both how-to and tutorial content. Include them even though they might seem obvious to knowledgeable users.
.Prerequisites (1)
:prerequisites-time: 30 minutes (2)
include::{includes}/prerequisites.adoc[] (3)
* <an additional prerequisite> (4)| 1 | Section heading for the prerequisites |
| 2 | Optional: An attribute that modifies the prerequisites |
| 3 | An include statement for the prerequisites.adoc file |
| 4 | Optional: An additional prerequisite not covered by the attributes |
By default, include::./_includes/prerequisites.adoc[] inserts the following 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)Optionally, you can add, remove, or modify the default prerequisites by inserting the following attributes on the line before the include::./_includes/prerequisites.adoc[] macro.
-
{prerequisites-time}: <number of minutes>overrides the default value of 15 minutes. For example,{prerequisites-time}: 30adds* Roughly 30 minutes. -
{prerequisites-no-maven}removes* Apache Maven <maven version>. -
{prerequisites-docker}adds* A working container runtime (Docker or Podman). -
{prerequisites-docker-compose}addsDocker and Docker Compose or Podman, and Docker Compose. -
{prerequisites-no-cli}removes* Optionally the Quarkus CLI if you want to use it. -
{prerequisites-no-graalvm}or{prerequisites-graalvm-mandatory}remove* Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build). -
{prerequisites-graalvm-mandatory}adds* Mandrel or GraalVM installed and configured appropriately.
For more information about these attributes, inspect the content of the docs/src/main/asciidoc/_includes/prerequisites.adoc file.
既存の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 the original content. Configure a URL redirect in the Quarkus.io Website GitHub repository by using the following steps:
-
Switch to the
quarkusio/quarkusio.github.iorepository, and open the_redirects/guidesfolder. -
破棄したい元のAsciiDocのソースファイル名と一致するファイル名のリダイレクトファイルをMarkdown形式で作成します。
-
Markdownリダイレクトファイルに、以下の内容を追加します:
--- permalink: /guides/<original_asciidoc_filename>/index.html (1) newUrl: /guides/<new_asciidoc_filename> (2) ---何処に
1 The name of the original AsciiDoc source file that you are retiring, without the .adocfile extension.2 The name of the AsciiDoc source file that you want to redirect to, without the .adocfile extension.
| 元のAsciiDocソースファイル名 | リダイレクト先となるファイル名 | Redirection file | プルリクエストの例 |
|---|---|---|---|
|
|
Use anchors to cross-reference in-file and cross-file content
An anchor, also called an ID, can be defined almost anywhere in the document, including on a section title, discrete heading, paragraph, image, delimited block, inline phrase, etc.
The callout functions for these anchors vary based on whether you call a local ID or the ID from another file, but the anchored ID creation remains the same.
Create an anchored ID
To create an ID for a new file or a section to which you want to refer, insert the anchor ID as follows:
-
Use lower-case characters.
-
Separate each word with a dash character.
-
Enclose the ID in double square brackets.
In this section, we will use an anchor created above the level-2 heading for demonstration purposes.
[[title-heading]]
== Title headingCall an anchored ID in the same file
同じファイルに作成されたアンカーを呼び出すには、 <<>> xrefマクロにアンカーIDを挿入してください。
<<title-heading>>This macro creates an URL with a name automatically sourced from the anchored heading, section, or table.
[Title heading] のように、逐語的な見出しやセクションの説明に <<>> 形式を使用しないでください。
|
When you want to specify a non-default caption for your URL, specify the anchored ID and desired name separated by , without white space.
<<title-heading,Title heading description that fits the context of your content>>Call an anchored ID from a different file
To call an anchor created in a different file, insert the anchor to an xref macro and specify the full name of the hosting file and the desired anchored ID.
xref:<other-file-name>.adoc#title-heading[Title heading]Breaking this example apart, we are using the xref macro to refer to another file (xref:<name-of-the-file>.adoc[Human-readable label]) and inserting the anchor ID for the target section (#title-heading) just after the file name.
For more guidelines on writing cross-references, including the recommended path attributes, see Cross-references.
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がインストールされていることが必要です。
Each IDE integration has its own configuration requirements. The Visual Studio Code IDE extension, for example, requires a definition of the Vale CLI path:
"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 separate PRs or ensure that a 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の説明にその関係性を含めてください。
GitHub automatically adds the area/documentation label to pull requests that contain changes to documentation files.
For more information about managing pull requests, see Information for Quarkus Committers.
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.
|
|
