Quarkusスタイル・コンテンツガイドライン
ガイドラインは、Quarkusドキュメントに必要な構造や構成に基づいた、明確で一貫性のあるコンテンツを提供するためのものです。
ウェブサイト掲載
このリポジトリからのコンテンツは、 Quarkus.io ウェブサイト に公開されます。
-
mainブランチからビルドされたドキュメントは毎晩公開されます(main-SNAPSHOT)。
-
その他のブランチのドキュメントは、リリース時に公開されます。
タイトルと見出し
コンテンツの種類に関わらず、メインタイトルや文書の見出しは必ず付けてください。
-
目標志向で、聴衆の言葉やキーワードを利用する
-
説明的で、フィラーワードを避ける
-
検索エンジンでの検索性を最適化するため、1 行あたり 3〜12 ワード、50〜80 文字程度とします
-
文例大文字スタイルでは
タイトルと見出しは、次の表に示すように、Quarkus のコンテンツタイプに固有のガイダンスにも従っている必要があります。
| Content type | 以下を行う必要があります | 良い例 | 悪い例 |
|---|---|---|---|
コンセプト |
|
Quarkus のセキュリティーと認証メカニズム |
Quarkus での反応型 SQL クライアントの発見 |
ハウツーガイド |
|
WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保 |
Quarkus での WebAuthn 認証の適用 |
参考 |
|
Hibernate Reactive API の設定プロパティー |
Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド |
チュートリアル |
|
クイックスタートの例を使用して、JVM モードの Quarkus アプリケーションを作成します。 |
アプリの作成 |
ファイル規約
ソースの場所
-
AsciiDocファイルが、Quarkus GitHub リポジトリー. の
docsモジュール内のsrc/main/asciidocディレクトリーにある。 -
設定ドキュメントは、Javaソースファイル内のJavaDocコメントから生成されます。
-
JavaやYAMLなどのソースファイルをAsciiDocのファイルから参照することも可能です。
出力先
- 設定リファレンス
-
設定リファレンスドキュメントは、MicroProfile Config ソースファイルで発見された Javadoc コメントから生成されます。これらの生成されたファイルは（プロジェクトルートから相対で）
target/asciidoc/generated/config/にあります。 - AsciiDocのHTMLへの出力
-
AsciiDocの処理で、
docs/target/generated-docs/にHTMLファイルを作成します。
テンプレート
コンテンツタイプに適したテンプレートで、新しいドキュメントファイルを作成してください:
- コンセプト
-
docs/src/main/asciidoc/_templates/template-concept.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の使用
ファイル名
Quarkus ドキュメントはフラットなヒエラルキーを使用します。
ファイル名の大部分は、そのタイトルを何らかの形で表現する必要があります。すべて小文字で、単語はハイフンで区切り、記号や特殊文字は避けてください。
- プレフィックス
-
関連ドキュメントをグループ化するには、共通の接頭辞を使用します。例えば、Quarkusドキュメントの執筆や貢献に関連するドキュメントは、
doc-というプレフィックスを共有します。 - 接尾辞
-
ドキュメントの種類を反映する接尾辞を使用します (オプション)。
-
概念関連のドキュメント用の
-concept.adoc -
ハウツーガイド用の
-howto.adoc -
リファレンス用の
-reference.adoc -
チュートリアル用の
-tutorial.adoc
-
ドキュメント構造
Quarkus テンプレートを使用して、推奨される Quarkus ドキュメントの構造とスタイルと、コンテンツが一致していることを確認します。
ドキュメントヘッダー
各ドキュメントは、ドキュメントスコープ属性のヘッダを定義すべきです。最低限，各ドキュメントは，idとタイトルを定義し，共通属性( _attributes.adoc )を含むべきです。
[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
\include::_attributes.adoc[] (3)
:diataxis-type: {type} (4)
:categories: contributing (5)| 1 | ファイル名をドキュメントのIDとして使用します。 |
| 2 | ドキュメントのタイトルを タイトルと見出し ガイダンスに従って定義します。 |
| 3 | 共通のドキュメント属性をインクルードする。 |
| 4 | concept、 howto、 reference、または tutorial から diataxis のタイプを指定します。 |
| 5 | 関連するカテゴリー (コンマ区切り) を指定します。 |
その他の共通ドキュメントヘッダー属性
:extension-status: preview-
この属性は、特別なタイプのコンテンツにフラグを立てるために使用します。有効な値:
experimentalpreview,stable(通常は使用しない) ,deprecated. - 概要
-
サマリーは、ドキュメントの簡潔な（26語以下の）説明を提供するために使用します。この属性の値は、ウェブサイト上のタイルやその他の説明で使用され、アブストラクト (前文) で概説したように、より新しい diataxis スタイルのドキュメントでは必要ありません。存在しない場合、要約の最初の文がタイルのサマリーを生成するために自動的に使用されます。
| 文書スコープの属性を扱うときは、空白に注意してください。文書ヘッダーは最初の空行で終わります。 |
アブストラクト (前文)
本文の最初の段落は要約として扱われ、プリアンブルとも呼ばれます。閲覧者がページの目的や意図をすぐに見つけ、理解できるような短い説明を追加します。要約の最初の文はサマリーとなり、 Quarkusガイドのホームページ のタイルに自動的に追加されます。
以下のガイドラインを参考にして、要約を書くようにしてください:
-
ユーザーオリエンテッドである: ユーザーにとって身近な用語やキーワードが含まれている。
-
簡潔である: 例えば、自己言及的な表現、フィラーワードを避ける。例:
-
"This document.."
-
"This tutorial…"
-
"The following…"
-
-
概要: 3 文以内にします。
|
最初のセンテンスで、コンテンツの価値やいくつかのメリットを26文字以内で説明しているようにして下さい。 |
最初の文が長すぎる場合、または Web サイトのタイルに収まらないほど簡略化できない場合は、ドキュメントヘッダー属性に :summary: 属性を定義して、その目的を果たすことができます。
詳細は、その他の共通ドキュメントヘッダー属性 を参照してください。
セマンティック改行
段落、リスト、および表のテキストは、[1] をレビューしやすいように細かく分割する必要があります。各文の終わりで新しい行を開始し、句間の自然な区切りで文自体を分割します。
セクション
セクションのタイトルは、タイトル・ケースではなく、センテンス・ケースで記述してください。
ドキュメントはタイトルから始めます。AsciiDoc では、タイトルは = Level 0 見出しとして定義されています。
必要に応じて、コンテンツをサブセクションに分割します。AsciiDoc では、サブセクションは == Level 1 から ====== Level 5 として定義されています。
どのレベルもスキップしないでください。
|
深い入れ子 (
コンテンツの種類と構成の詳細は、Quarkusドキュメントのコンテンツの種類 を参照してください。 |
リンク
一般的に、素のリンクや自動リンクよりも urlマクロ の方が望ましいです。特に、リンクが他のテキストの途中に含まれている場合は、人間が読めるテキストを用意してください。
|
属性を持つ URL マクロリンク
URLマクロは、リンクを別ウィンドウで開くなど、関連しそうな 追加属性 もサポートしています。 上記のソースはこの AsciiDoc構文クイックリファレンス を作成します。 |
クロスリファレンス
Quarkus のドキュメントは、いくつかの異なる環境でソースから構築されています。
クロスリファレンスソース属性
クロスリファレンスで属性を使用することで、これらの環境でドキュメントを構築できるようになります。
| 属性 | 説明 |
|---|---|
|
収集されたサンプルソースファイルを含むディレクトリーへの相対パス |
|
ドキュメントガイドのソース例への相対パス |
|
生成された設定ファイル |
|
イメージが格納されているディレクトリーへの相対パス |
|
部分的な/再利用可能なコンテンツを含むディレクトリーへの相対パス |
コンテンツを相互参照する場合は、常にドキュメント間の xref: 構文を使用し、人間が判読できるラベルをリンクに付けてください。
xref:doc-concept.adoc[Quarkus Documentation concepts] (1)| 1 | クロスリファレンスは xref: で始まり、 [Quarkus ドキュメントの概念] など、読みやすい説明を提供します。 |
ファイル内およびファイル間ナビゲーションのためのアンカー
-
アンカーIDを作成するには、小文字を使用し、各単語を
-で区切り、以下の例のように[[]]でIDを囲んでください。[[title-heading]] == Title heading -
同じファイルに作成されたアンカーを呼び出すには、
<<>>xref マクロにアンカーIDを挿入してください。<<title-heading>> -
カスタムURLキャプションの例でアンカーを作成するには、アンカーIDと希望する名前を空白なしで
,で区切って指定します。<<title-heading,Title heading description that fits the context of your content>><<Title heading>>のように、 逐語的な見出しやセクションの説明に<<>形式を使用しないでください。 -
別のファイルからアンカー付きIDを呼び出すには、完全なファイル名とアンカー付きIDを
#で区切って使い、人間が読めるURLキャプションを指定してください。xref:<other-file-name>.adoc#title-heading[Title heading] -
別のファイルを参照するには、完全なファイル名構文でxrefマクロを使い、常に人間が読めるURLキャプションを指定してください。
xref:<name-of-the-file>.adoc[Human-readable label]アンカー ID の詳細は、Quarkus ドキュメントへのコントリビューションガイドの アンカーを使用してファイル内およびファイル間のコンテンツを相互参照する セクションを参照してください。
クロスリファレンスのフレーズ
一貫性とコンテキストの明確さを保つために、クロスリファレンスの文章を作成する場合には次のガイドラインに従ってください。
-
前のセクションの
xrefガイダンスを使用して、セクションへの直接ハイパーリンクを提供します。 -
セクションの完全なタイトルを指定し、文頭に大文字を使用します。
-
セクションタイトルの前に定冠詞 the を追加し、タイトルの直後に section を指定します。
-
ガイドのタイトルに Quarkus という単語がすでに含まれていない限り、ガイドのタイトルの前に定冠詞 the と Quarkus を追加します。
-
ガイドのタイトルを二重引用符で囲み、タイトルの直後にガイドと指定します。
-
文脈が必要な場合は、次のフレーズで始めます。
-
"For more information about …"
-
| 正しい | 間違い |
|---|---|
詳細は、Quarkus の「Hibernate Validator を使用した検証」ガイドの ValidatorFactory の設定 セクションを参照してください。 |
詳細は、VALIDATION WITH HIBERNATE VALIDATOR ガイド の 'ValidatorFactory の設定' セクションを参照してください。 |
詳細は、Quarkus の「アプリケーションデータキャッシュ」ガイドの CacheKeyGenerator を使用したキャッシュキーの生成 セクションを参照してください。 |
詳細は、CacheKeyGenerator を使用したキャッシュキーの生成 を参照してください。 |
詳細は、Quarkus の「OpenID Connect (OIDC) 認可コードフローメカニズム」ガイドの PKCE 関連のセクション を参照してください。 |
詳細は、OpenID Connect (OIDC) 認可コードフローメカニズム を参照してください。 |
リファレンスソースコード
ドキュメントにソースコードや例を含める方法は多数あります。
一番簡単なのは、このようにファイルに直接書き込むことです。
[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 ディレクトリにファイルをコピーする際に使用する簡略化されたターゲットファイル名を定義します。 |
この方法でコピーされたコンテンツは、 ../_generated-doc/latest/examples source属性で参照されます。ソースファイル内にリテラル文字列 {{source}} が存在する場合は、コピー先のソースファイルのパスに置き換えられます。
-
コピーされる元ファイルは
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: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
ドキュメント属性と変数
カテゴリー
Quarkusのドキュメントは、以下のカテゴリーに分類されています。
| カテゴリー | 説明 |
|---|---|
|
他の言語、すなわちKotlinとScalaのサポート |
|
Quarkusのランタイムとエコシステム・アーキテクチャ |
|
ビジネスオートメーション統合 |
|
クラウドサービスとの統合・サポート |
|
コマンドラインアプリケーション |
|
他の言語やフレームワークとの互換性 |
|
Quarkusに貢献するためのガイダンスとリファレンス。 |
|
Quarkus の仕組みに関する情報 |
|
Quarkusでのデータソースの使用に関連するトピック |
|
入門用資料 |
|
インテグレーションエクステンション（Camel）のサポート |
|
Kafka、AMQP、RabbitMQのようなメッセージングシステムとの統合。 |
|
その他 |
|
ネイティブ実行可能ファイルに関する全て |
|
ランタイムとアプリケーションのobservabilityを高めるためのエクステンションと統合 |
|
セキュリティー |
|
シリアル化 |
|
ツール |
|
ウェブ |
|
エクステンションの作成 |
document header のcategories 属性行に少なくとも 1 つのカテゴリーを追加して、タグ付けを行い、見つけやすくします。複数のカテゴリーを追加するには、コンマで区切られた値を使用します。たとえば、以下のようになります:
:categories: contributing, dataQuarkus ドキュメント変数
以下の変数は、時間の経過とともに変化する重要な情報を外部化しています。このような情報を参照するには、中括弧で囲まれた {} 内の変数を使用する必要があります。
使用する外部化変数の完全なリストを次の表に示します。
| プロパティ名 | 値 | 説明 |
|---|---|---|
|
|
プロジェクトの現在のバージョン。 |
|
プロジェクトのホームページの場所。 |
|
|
プロジェクトの GitHub 組織の場所。 |
|
|
Quarkus GitHub の URL の共通ベース接頭辞。 |
|
|
ドキュメントで参照されている |
|
|
メインソースアーカイブへの Quarkus URL。 |
|
|
ソースファイルを参照するために使用される、メインのブロブソースツリーへの Quarkus URL。 |
|
|
メインソースツリールートへの Quarkus URL。 |
|
|
Quarkus の課題ページへの URL。 |
|
|
Quarkus 用に配信されるコンテナーイメージのセットへの Quarkus URL。 |
|
|
チャットの URL |
|
|
メーリングリストに登録するために使用される電子メール。 |
|
|
メーリングリストのインデックスページです。 |
|
|
Quickstarts URL 共通ベースプレフィックス。 |
|
|
ドキュメントで参照されている |
|
|
|
メインソースアーカイブへのクイックスタート URL です。 |
|
メイン blob ソースツリーへのクイックスタート URL。 |
|
|
メインソースツリーのルートへのクイックスタートの URL。 |
|
|
|
使用する GraalVM の推奨バージョン。 |
|
|
使用する GraalVM のビルダーイメージタグ (例: |
