ドキュメントスタイルガイド¶

このガイドには、新規コンテンツの作成および既存コンテンツの翻訳に関する、期待されるスタイル、MkDocs固有の構文、各種必須ツール、およびドキュメント翻訳についての情報が含まれています。

一般的なスタイル¶

見出しやタイトルでは、最初の単語のみ大文字で始めるべきです。
米国式スペルを優先しますが、プログラミング特有の慣用表現（例：「apps」）や名詞の動詞化（例：「scrollable」）については一部例外を認めます。
「artefact」および「artefacts」の綴りは、記載の通りです。
句点の後は半角スペースを1つ使用します。
スペースで囲まれた単一のハイフンを長横線（またはHTMLの—リテラル）として使用します。
製品名への言及は、製品が推奨する大文字表記を使用してください（例："macOS", "GTK", "pytest", "Pygame", "PyScript"）。
ある用語が「暗号」として使用されている場合、辞書に追加するのではなく、シングルバッククォートで囲んでインラインコードとして引用すべきである。
ユーザーが取るべき行動を説明する際に、「単に」「ただ」「簡単に」といった表現の使用は避けます。これらの表現は、特にユーザーが困難を経験している場合に、軽蔑的に受け取られる可能性があります。

相互参照情報¶

ドキュメント内のコンテンツは可能な限り相互参照すべきです。このセクションでは、参照する情報の種類に基づいて実施できる様々な方法を説明します。

MkDocsは標準的なMarkdown形式のリンクをレンダリングします。標準的なMarkdown形式のウェブハイパーリンクは以下の通りです：

[Link text](https://example.com/)

この形式を使用してローカルファイルへのリンクを作成することもできます:

[Link text](path/to/file.md)

ファイルの特定セクションやAPIドキュメントを参照するには、MkDocsの参照リンク形式を使用する必要があります。

カスタムMarkdownアンカーとコンテンツ相互参照¶

Markdownは、ヘッダーの内容に基づいて、すべてのヘッダー（1行で1つから6つの#記号で始まるもの）に対してアンカーを生成します。例えば、このセクション用に生成されたアンカーはcustom-markdown-anchors-and-content-cross---referencingです。ただし、当社の翻訳の仕組み上、セクションヘッダーを参照する場合には、常にカスタムアンカーが必要です。

MkDocsは、修正されたMarkdownリンクを使用してドキュメント内の様々な要素へリンクできる参照リンク構文のレンダリングをサポートしています。これには、カスタムMarkdownヘッダーやテキストアンカーなどへのリンクが含まれます。

MkDocs リファレンスリンクは、以下の形式で記述されたリンクです：

[Link text][link-target]

カスタムヘッダーとコンテンツアンカーが必要です

BeeWareドキュメントにおいて、テキストコンテンツ内でMkDocs参照リンクを介して参照されるヘッダーまたはコンテンツセクションには、必ずカスタムアンカーを添付する必要があります。そうしないと、ヘッダーコンテンツが翻訳された際にリンクが壊れる可能性があります。

ヘッダーアンカーへのリンクを設定するには、対象コンテンツ用にカスタムアンカーを生成する必要があります。カスタムアンカーの設定における一般的な構文は以下の通りです：

# Header text { #anchor-name }

例えば、このセクションのアンカーをcustom-anchorsにカスタマイズするには、以下の書式設定を行います：

## Custom Markdown anchors { #custom-anchors }

テキストやコードブロックを含む一般的なコンテンツにもアンカーを作成できます。リンク先となるコンテンツの上部に、改行を上下に含めた以下のフォーマットを記述してください：

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

カスタムアンカーを作成したら、同じ文書内やドキュメントの他の部分からそれらにリンクできます。

標準マークダウンでは、アンカーへのリンクは_同じファイル内_に設定され、以下の形式で記述されます：

[Link text](#anchor-name)

別ドキュメント内のアンカーへのリンクには、MkDocsの参照リンクスタイルが使用されます。その書式は以下の通りです：

[Link text][anchor-name]

APIリファレンスリンク¶

MkDocsのリファレンスリンク機能は、APIドキュメントの相互参照もサポートしています。これには、ドキュメント化されたクラス、クラスメソッドまたは属性、および特定の外部ドキュメント参照が含まれます。

ドキュメント化されたクラス、クラスメソッド、または属性へのリンクには、同じファイル内からリンクする場合でも別ファイルからリンクする場合でも、複数の方法があります。クラスなどにリンクする際は、名前をインラインコードとして表示するために、最初の角括弧内にバッククォートを含める必要があります。インラインコードとして表示すべきでないカスタムテキストを使用する場合のみ、バッククォートは不要です。 2つ目の角括弧には、いかなる場合もバッククォートを含めてはいけません。

名前空間を表示しながらクラスへのリンクを張る場合、以下の形式で記述します:

[`module.ClassName`][]

クラス名のみを表示しながらクラスにリンクする場合は、以下の形式で記述します：

[`ClassName`][module.ClassName]

属性は上記と同じで、属性名が含まれます。以下は名前空間を表示します：

[`module.ClassName.attributename`][]

クラスと同様に、属性名のみを表示する場合は以下の形式で記述します：

[`attributename`][module.ClassName.attributename]

メソッドは名前空間の後に()を付けて表示する必要があるため、属性とは異なる方法で処理しなければなりません。メソッドへのリンクの適切な方法は以下の通りです：

[`module.ClassName.methodname()`][module.ClassName.methodname]

以下はクラス名とメソッド名のみを表示します。これには名前の後に括弧を含めることも必要です：

[`Classname.methodname()`][module.Classname.methodname]

クラス、メソッド、または属性にリンクしながら任意のテキストを表示するには、該当する名前空間と共に同じメソッドを使用します。クラスに対してこれを行う場合の書式は次の通りです：

[link text][module.ClassName]

PythonのコアドキュメントやPillowのドキュメントにも直接リンクできます。例えば、intのドキュメントにリンクするには：

[`int`][]

Pillow Image のドキュメントへのリンク:

[`PIL.Image.Image`][]

コードブロックのヒント¶

言語とコードの強調表示¶

コードブロック内のコードの言語は、最初の3つのバックティックの直後にスペースなしで言語名を指定することで設定できます。これにより、コードがレンダリングされた際に適切なコードの強調表示が行われます。例えばPythonを指定する場合は、コードブロックを```pythonで開始します。

コンソールコマンドとコピーボタン¶

コンソールコマンドや出力のあるコマンドを含める場合、Unix系（macOSを含む）オペレーティングシステムを記述する場合はconsole、Windowsを記述する場合はdosconで囲みます。オペレーティングシステムが提供するプロンプトを含めることも可能です。コピーボタンをクリックするとコマンド部分のみがコピーされます。例えば、コードブロックを```consoleで開始し、以下の内容を含める場合：

$ mkdir test
$ ls
test

次に、コードブロックのコピーボタンをクリックすると、コマンドのみがコピーされ、プロンプトと出力は無視されます。これにより、コンソールコマンドであることを示しつつ、ユーザーがコピーボタンを効果的に使用できるようにします。

特定のコード行を強調表示する¶

特定のコード行をハイライトできます。例えば、2行目をハイライトするには、言語名の後にスペースを挿入し、その後に{hl_lines="2"}を追加します。つまり、コードブロックは```python {hl_lines="2"}で始まります。結果は次のようになります：

import toga
from toga.style.pack import COLUMN, ROW

複数の異なる行をハイライトできます。例えば、python {hl_lines="3 5 9"} とすると行3、5、9がハイライトされます。行の範囲もハイライトできます。例えば、python {hl_lines="3-8"} とすると行3から8までがハイライトされます。複数の範囲をハイライトすることも可能です。例えば、python {hl_lines="9-18 23-44"} とします。

特定の書式設定を必要とするマークダウン要素¶

翻訳ファイルの生成方法上、警告文、注釈、タブ、Jinjaディレクティブ、画像キャプションや配置などにおいて、Markdown構文で必要な改行を含めることが重要です。

戒めと注記¶

警告は以下のように書式設定する必要があります。警告の開始と終了の前後に改行を入れることを含みます：

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

これはサポートされている警告タイプすべてで同様に機能します。例えば、注記警告も同様の書式と改行を必要とします：

Content above.

/// note | Note title

Note text here.

///

Content below.

すべてのサポートされている警告タイプは、警告として使用できます。

タブ付きコンテンツ¶

タブ付きコンテンツは以下のようにフォーマットされます。コンテンツブロックの開始前と終了後に改行を含みます：

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

ネストされた警告を含むタブは、以下の形式で書式設定されます。コンテンツブロックの前後には改行が含まれます：

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

折りたたまれたコンテンツ¶

折りたたまれたコンテンツは、改行を含めて以下の形式で表示されます：

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

すべてのサポートされている警告タイプは折りたたみコンテンツで使用可能ですが、それらをdetails-admonitiontypeとして宣言する必要があります。したがって、「注意」タイプの折りたたみブロックはdetails-note（上記参照）、「警告」タイプの折りたたみブロックはdetails-warningとなり、以下同様です。

Jinja ディレクティブ¶

ドキュメントには、テキスト内でJinjaディレクティブを使用する機能がいくつか存在します。Jinjaディレクティブ機能を使用する部分はすべて改行で囲む必要があります。例えば、BeeWareチュートリアルには、メインページに表示する警告を決定するための変数に基づくJinja条件分岐が含まれています。これらは以下のようにフォーマットされています：

Content above.



Content below.

記号やテキストを置換するための構文も存在する。この構文は変数を対応する二重中括弧で囲んだものであり、単独の行にある場合は前後に改行を含めなければならない。

Content above.

{{ variable }}

Content below.

画像の書式設定¶

画像には幅を設定でき、左揃え、右揃え、中央揃えが可能です（「中央揃え」には注意点があります）。アクセシビリティのため、画像には常に意味のある代替テキストを含める必要があります。

画像の幅を300pxに設定する場合、以下の形式で記述します：

![Image alt text](../path/to/image.png){ width="300px" }

画像を左（または右）揃えにする場合、以下の形式で記述します：

![Image alt text](../path/to/image.png){ align=left }

画像にキャプションを追加するには、キャプションの前後に改行が必要であり、以下の形式で記述します：

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

画像の中心を揃えることはalign属性では不可能です。回避策として、画像の後に空のキャプションを配置すると中央揃えになります。各セクション間、および前後には改行を含める必要があります。以下の形式で記述します：

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

特定のMarkdown書式設定を備えたプラグイン¶

以下のセクションでは、特定のMarkdown書式設定を必要とするプラグインの活用方法について説明します。

スニペットを使用して外部コンテンツを含める¶

ローカルファイルやURLから外部コンテンツを含める方法の詳細については、Snippets拡張機能のドキュメントを参照してください。ドキュメントに実行が必要なJinjaディレクティブが含まれていない限り、Snippetsを使用すべきです（Jinjaの実行はSnippetsの処理と並行して行われるため、ファイル内のJinjaは処理されません）。ファイルの特定部分を個別に含めるための区切り記号を使用したい場合、スニペットは必須です。例えば、ソース文書が複数のセクションに分割され、それぞれが別々に挿入される場合などが該当します。

重要な注意事項：

スニペット識別子として-8<-を使用します。ドキュメントには複数のオプションが記載されていますが、当社のスタイルに従ってください。
Files found in BeeWare Docs Tools shared content are treated as "local" content. Therefore, you will either use only the filename, as in -8<- "docs-style-guide.md", or if the content is in a subdirectory, only the directory and filename, as in -8<- "style/docs-style-guide.md".
GitHub上のファイルからURL経由で外部コンテンツを含める場合、必ず生のコンテンツURLを使用してください。そうしないと、埋め込んだ場所にウェブページ全体がレンダリングされてしまいます。

マクロを使用してBeeWare Docs Toolsの共有コンテンツを組み込む¶

Macros MkDocs plugin を使用すると、BeeWare Docs ツールの共有コンテンツディレクトリからコンテンツを含めることもできます。この方法は、ドキュメントに実行が必要な Jinja ディレクティブが含まれている場合に必要であり、この状況でのみ使用すべきです。URL 経由の外部コンテンツでは機能しません。Macros variable-replacement mechanism はこの方法と互換性があります。

マクロを使用してコンテンツを含める方法には以下の選択肢があります：

ドキュメントを他の手動変更なしで含めたい場合は、include Jinja構文を使用してください。
ドキュメント内にJinja extends構文を含めている場合は、[(https://jinja.palletsprojects.com/en/stable/templates/#child-template) Jinja構文]blockを使用してください。これにより、特定のセクションを上書きしたり追加したりできます。

`pyspelling`¶

私たちはpyspellingスペルチェッカーを使用しています。これはlintチェック中に実行されます。

pyspellingが誤字を識別する場合、ほとんどの場合、ドキュメントの内容で修正する必要があります。

pyspelling辞書に含まれていない有効な単語を識別する稀なケースでは、次の2つの選択肢があります：

その単語が複数回再利用される可能性が高い場合は、その単語をspelling_wordlistディレクトリ内のdocs文書にアルファベット順で追加すべきです。
その単語が再び使用される可能性が低い場合、<nospell> / </nospell> タグで囲むことで、pyspelling はそれをインラインで無視します。