Back to Guides

About Quarkus documentation

Quarkus ドキュメントの構造と設定に関する詳細なリファレンスです。

ソースの場所

Quarkus のドキュメントソースは、リリース時にビルドされ、 Quarkus.io のウェブサイト に同期されます。

  • Quarkus コアおよびほとんどのエクステンションのドキュメントは、 Quarkus GitHub リポジトリー の docs モジュールにあります。

  • Quarkiverse やその他のサードパーティーのエクステンションのドキュメントは、それらのリポジトリーから直接取得されます。

Asciidoc ファイルは docs モジュール内の src/main/asciidoc ディレクトリーにあります。

テンプレート

コンテンツタイプに適したテンプレートを使用して、新しいドキュメントファイルを作成します。

コンセプト

docs/src/main/asciidoc/_templates/template-concepts.adoc の使用

ハウツーガイド

docs/src/main/asciidoc/_templates/template-howto.adoc の使用

参考

docs/src/main/asciidoc/_templates/template-reference.adoc の使用

チュートリアル

docs/src/main/asciidoc/_templates/template-tutorial.adoc の使用

出力先

設定リファレンス

MicroProfile Config ソースファイルで発見された Javadoc コメントは、config reference ドキュメントを生成するために使用されます。これらの生成されたファイルは target/asciidoc/generated/config/ (プロジェクトルートから) に格納されています。

Asciidoc 出力の HTML 化

asciidoc 処理のローカルレンダリング結果 (Web サイトのドキュメント生成に使われるものと似ていますが、同一ではありません) は、 docs/target/generated-docs/ にあります。

タイトルと見出し

コンテンツの種類に関わらず、メインタイトルや文書の見出しは必ず付けてください。

  • 目標志向で、聴衆の言葉やキーワードを利用する

  • 説明的で、フィラーワードを避ける

  • 検索エンジンでの検索性を最適化するため、1 行あたり 3〜12 ワード、50〜80 文字程度とします

  • 文例大文字スタイルでは

タイトルと見出しは、次の表に示すように、Quarkus のコンテンツタイプに固有のガイダンスにも従っている必要があります。

Table 1. Quarkus のさまざまなコンテンツタイプに対応したタイトルガイダンス
Content type 以下を行う必要があります 良い例 悪い例

コンセプト

  • Start with a noun that names the concept or topic

  • Never start with an active verb, for example, an action word like configure, install, or start

  • Finish the implied sentence: "Understanding … "

Quarkus のセキュリティーと認証メカニズム

Quarkus での反応型 SQL クライアントの発見

ハウツーガイド

  • Start with an active verb in the imperative verb form, for example, ‘Create a …​’ or ‘Secure a …​’

  • Be action-oriented or task-oriented, rather than feature-oriented

  • Finish the implied sentence: "How to.."

WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保

Quarkus での WebAuthn 認証の適用

参考

  • Use a noun phrase to concisely summarize the content of the document

  • Not include the word 'reference'

  • Finish the implied sentence: "About …​"

Hibernate Reactive API の設定プロパティー

Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド

チュートリアル

  • Start with an active verb in the imperative verb form, for example, ‘Create a …​’ or ‘Secure a …​’

  • State what task the user will complete, with emphasis on the key topic or demonstrated activity

  • Be action-oriented or task-oriented, rather than feature-oriented

  • Be led by the needs of the user in learning mode.

  • Finish the implied sentence: "In this tutorial, you will… "

クイックスタートの例を使用して、JVM モードの Quarkus アプリケーションを作成します。

アプリの作成

ファイルの命名規則

Quarkus のドキュメントは、発見しやすくするために、かなりフラットな構造で保存されています。ファイル名の大部分は、そのタイトルを表すものでなければなりません。すべて小文字を使用し、単語はハイフンで区切り、記号や特殊文字は使用しないでください。

プレフィックス

関連するドキュメントをグループ化するために、共通の接頭辞を使用します。例えば、Quarkus のドキュメントを書くことに関連するすべてのドキュメントは、プレフィックスとして`doc-`が付きます。

接尾辞

ファイル名は、ドキュメントの種類を反映したものにします:

  • コンセプトドキュメントは -concepts.adoc で終わる必要があります。

  • ハウツーガイドは -how.adoc で終わるべきである。

  • リファレンスは -reference.adoc で終わる必要があります。

  • チュートリアルは -tutorial.adoc で終わる必要があります。

Asciidoc 構文

Quarkus docs は、Asciidoc 構文を使用しています。次のリンクは、Asciidoc の構文と一般的な規則に関する背景を説明しています。

セマンティック改行

段落、リスト、および表のテキストは、[1] をレビューしやすいように細かく分割する必要があります。各文の終わりで新しい行を開始し、句間の自然な区切りで文自体を分割します。

アブストラクト (前文)

検索しやすさを最適化するには、ユーザー指向のキーワードを使用して短い説明を追加し、ドキュメントの目的、タスク、および意図を 3 センテンス以内で要約します。「このドキュメント..」、「このチュートリアル..」、「次の..」などの自己言及的な表現やつなぎ言葉は避けてください。 ユーザーがコンテンツを読むことで得られるメリットについて言及することも役に立ちます。

要約の最初の文は、26文字以内でコンテンツの価値と何らかの利益を説明する必要があります。これは、 Quarkusガイド のホームページに自動的に表示されるためです。

自動目次 (TOC)

文書のヘッダーで :toc: preamble を使うと、文書のアブストラクト (またはプリアンブル) の後に自動生成された TOC を挿入できます。たとえば、この文書のヘッダーには次のように書かれています：

[id="reference-doc-quarkus-documentation"]
= Quarkus documentation reference
include::_attributes.adoc[]
:toc: preamble

セクションの使用

セクションのタイトルは、タイトルケースではなく、センテンスケースで記述すること。

すべての文書はタイトル ( = Level 0 の見出し) で始まり、レベルを飛ばすことなく適切なサブセクション ( = Level 1 から = Level 5 ) に分割されなければなりません。

深い入れ子 ( ====== Level 4 、 ====== Level 5 ) は、可能な限り避ける必要があります。深くネストされたセクションになってしまった場合は、次のことを考慮してください。

  • この情報は適切な場所にありますか? 例えば、これがリファレンスであれば、このコンテンツの一部をコンセプトドキュメントやハウツーガイドに移すべきでしょうか?

  • コンテンツをよりシンプルに消費できるように再編成することは可能か？

コンテンツの種類と設定の詳細については、 Quarkus ドキュメントのコンセプト を参照してください。

一般に、素のリンクや自動リンクよりも、 url マクロ を使う方が望ましいです。特に、リンクが他のテキストの途中に含まれている場合は、人間が読みやすいテキストを提供してください。

属性を持つ URL マクロリンク

URL マクロは、リンクを別ウィンドウで開くなどの関連性が考えられる 追加属性 もサポートしています。

https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Asciidoc Syntax Quick Reference,window=_blank,opts=nofollow]

上記のソースからこのようなリンクが生成されます: link: Asciidoc Syntax Quick Reference

クロスリファレンス

Quarkus のドキュメントは、いくつかの異なる環境でソースから構築されています。相互参照で属性を使用して、これらの環境全体でドキュメントを構築できるようにします。

Table 2. クロスリファレンスソース属性
属性 説明

{code-examples}

収集されたサンプルソースファイルを含むディレクトリーへの相対パス

{doc-guides}

ドキュメントの adoc ファイルへの相対パス (例:doc-concepts.adoc)

{doc-examples}

ドキュメントガイドのソース例への相対パス

{generated-dir}

生成された設定ファイル *.adoc への相対パス。

{imagesdir}

イメージが格納されているディレクトリーへの相対パス

{includes}

部分的/再利用可能なコンテンツ (*.adoc ファイル) を含むディレクトリーへの相対パス

コンテンツを相互参照する場合は、常にドキュメント間の xref: 構文を使用し、人間が判読できるラベルをリンクに付けてください。

Cross-reference example
xref:{doc-guides}/doc-concepts.adoc[Quarkus Documentation concepts] (1)
1 相互参照は xref: で始まり、相互参照ソース属性 ({doc-guides})、および読みやすい説明を提供します: [Quarkus ドキュメントの概念]

リファレンスソースコード

ドキュメントにソースコードやサンプルを含めるには、さまざまな方法があります。

一番簡単なのは、このようにファイルに直接書き込むことです。

[source,java]
----
System.out.println("Hello, World!");
----

チュートリアルなどのドキュメントでは、定期的にビルドおよびテストされているソースコードを参照したい場合があります。Quarkus ドキュメントモジュールのビルドは、 *-examples/yaml ファイルに列挙されたソースファイルを (プロジェクトルートから) target/asciidoc/examples ディレクトリーのフラット化された構造にコピーします。

examples:
- source: path/to/source/file/SomeClassFile.java (1)
  target: prefix-simplified-unique-filename.java (2)
1 コピーするソースのパスを定義する
2 target/asciidoc/examples ディレクトリにファイルをコピーする際に使用する簡略化されたターゲットファイル名を定義します。ファイル名には、関連/消費ドキュメントと同じプレフィックスを使用することをお勧めします。

この方法でコピーされたコンテンツは、 {code-examples} source属性を使って参照されます。コピーされたファイルにリテラル文字列 {{source}} が含まれている場合、そのリテラル値はソースファイルのパスに置き換えられます。

Micrometer例

  • コピーされる元ファイルは

    integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java

  • docs で使いたいターゲットファイル名は。

    telemetry-micrometer-tutorial-example-resource.java.

  • ソースファイル名とターゲットファイル名は docs/src/main/asciidoc/telemetry-examples.yaml で宣言されます。

    examples:
- source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
  target: telemetry-micrometer-tutorial-example-resource.java

  • そして、このソースファイルからのスニペットは、以下のパスを使ってインクルードされます:

    {code-examples}/telemetry-micrometer-tutorial-example-resource.java.

  • ソースファイルには、以下のコメントが記載されています。

// Source: {{source}}

  • コピーされたファイルには、代わりにこのコメントが含まれています。

// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java

Quarkus ドキュメント変数

以下の変数は、時間の経過とともに変化する重要な情報を外部化しています。このような情報を参照するには、中括弧で囲まれた {} 内の変数を使用する必要があります。

使用する外部化変数の完全なリストを次の表に示します。

Table 3. 変数
プロパティ名 値 説明

{quarkus-version}

2.13.9.Final

プロジェクトの現在のバージョン。

{quarkus-home-url}

https://quarkus.io

プロジェクトのホームページの場所。

{quarkus-org-url}

https://github.com/quarkusio

プロジェクトの GitHub 組織の場所。

{quarkus-base-url}

https://github.com/quarkusio/quarkus

Quarkus GitHub の URL の共通ベース接頭辞。

{quarkus-clone-url}

https://github.com/quarkusio/quarkus.git

ドキュメントで参照されている git clone の Quarkus URL。

{quarkus-archive-url}

https://github.com/quarkusio/quarkus/archive/main.zip

メインソースアーカイブへの Quarkus URL。

{quarkus-blob-url}

https://github.com/quarkusio/quarkus/blob/main

ソースファイルを参照するために使用される、メインのブロブソースツリーへの Quarkus URL。

{quarkus-tree-url}

https://github.com/quarkusio/quarkus/tree/main

メインソースツリールートへの Quarkus URL。

{quarkus-issues-url}

https://github.com/quarkusio/quarkus/issues

Quarkus の課題ページへの URL。

{quarkus-images-url}

https://github.com/quarkusio/quarkus-images/tree

Quarkus 用に配信されるコンテナーイメージのセットへの Quarkus URL。

{quarkus-chat-url}

https://quarkusio.zulipchat.com

チャットの URL

{quarkus-mailing-list-subscription-email}

quarkus-dev+subscribe@googlegroups.com

メーリングリストに登録するために使用される電子メール。

{quarkus-mailing-list-index}

https://groups.google.com/d/forum/quarkus-dev

メーリングリストのインデックスページです。

{quickstarts-base-url}

https://github.com/quarkusio/quarkus-quickstarts

Quickstarts URL 共通ベースプレフィックス。

{quickstarts-clone-url}

https://github.com/quarkusio/quarkus-quickstarts.git

ドキュメントから参照される git clone のクイックスタート URL です。

{quickstarts-archive-url}

https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip

メインソースアーカイブへのクイックスタート URL です。

{quickstarts-blob-url}

https://github.com/quarkusio/quarkus-quickstarts/blob/main

メイン blob ソースツリーへのクイックスタート URL。

{quickstarts-tree-url}

https://github.com/quarkusio/quarkus-quickstarts/tree/main

メインソースツリーのルートへのクイックスタートの URL。

{graalvm-version}

22.3

使用する GraalVM の推奨バージョン。

{graalvm-flavor}

22.3-java17

使用するGraalVMのビルダーイメージタグ。例: 22.3-java17 。 java17 バージョンを使用して下さい。

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Roq on Quarkus, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.