ドキュメンテーション スタイル ガイド#
このガイドには、Matplotlib ドキュメントの言語と書式設定に関するベスト プラクティスが含まれています。
こちらもご覧ください
寄稿の詳細については、「ドキュメントの作成」 セクションを参照してください。
説明言語#
説明文については、次のガイドラインは明確で簡潔な言葉を使用するためのものです。
用語#
Matplotlib には、ドキュメントの信頼性と一貫性の基準となる重要な用語がいくつかあります。それらは交換可能ではありません。
学期 |
説明 |
正しい |
正しくない |
|---|---|---|---|
プログラミング用の Matplotlib 作業スペース。 |
|
||
Figure 内のサブプロット。プロット要素を含み、追加の詳細のプロットと構成を担当します。 |
|
||
ビジュアルを表示するさまざまな Matplotlib オブジェクト。 |
|
||
目盛り、目盛りラベル、スパイン、およびエッジを含む参照マークの人間が判読できる 1 次元オブジェクト。 |
|
||
明示的なオブジェクト指向プログラミング (OOP) |
Matplotlib でのプログラミングの明示的なアプローチ。 |
|
|
暗黙、
|
|
|
|
文法#
件名番号
アクションを指定する直接指示には、二人称命令文を使用します。二人称代名詞は、個人固有の文脈と所有格の参照用です。
正しい |
正しくない |
|---|---|
|
ソース ディレクトリから Matplotlib をインストールできます。インストールに問題がある場合は、追加のサポートを見つけることができます。 |
時制#
説明には現在単純時制を使用します。可能であれば、未来形やその他の法助動詞は避けてください。
正しい |
正しくない |
|---|---|
視覚化のための Matplotlib の背後にある基本的なアイデアには、データを取得し、関数とメソッドを使用してデータを変換することが含まれます。 |
Matplotlib はデータを取得し、関数とメソッドを介して変換します。さまざまな種類のビジュアルを生成できます。これらは、Matplotlib を使用するための基本になります。 |
ボイス番号
アクティブな文で書きます。受動態は、警告プロンプトに関連する状況または条件に最適です。
正しい |
正しくない |
|---|---|
関数 |
グラフは
|
引数がない場合、関数によってエラー メッセージが返されます。 |
引数がない場合、関数からのエラー メッセージが表示されます。 |
文の構造#
主語-動詞-目的語の順番を規則正しく使って、短い文章で書きましょう。文中の調整接続詞を制限します。代名詞の参照と従属接続句は避けてください。
正しい |
正しくない |
|---|---|
|
Matplotlibの |
この |
この |
暗黙的なアプローチは、単純なプロットを生成するための便利なショートカットです。 |
プロットを生成するための便利なショートカットが必要なユーザーは、暗黙的なアプローチを使用します。 |
フォーマット#
次のガイドラインでは、コードを組み込み、Matplotlib ドキュメントに適切な書式を使用する方法を指定します。
コード番号
Matplotlib は Python ライブラリであり、ドキュメントについても同じ標準に従っています。
出力#
.py例のファイルを使用して Matplotlib でビジュアルを生成する場合は、ビジュアルmatplotlib.pyplot.showを表示する でビジュアルを表示します。ドキュメントから Python の出力行を削除してください。
正しい |
正しくない |
|---|---|
plt.plot([1, 2, 3], [1, 2, 3])
plt.show()
|
plt.plot([1, 2, 3], [1, 2, 3])
|
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 2, 3])
fig.show()
|
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [1, 2, 3])
|
reStructuredText #
Matplotlib はドキュメントに reStructuredText マークアップを使用します。Sphinx は、これらのドキュメントをアクセシビリティと可視性のために適切な形式に変換するのに役立ちます。
リスト#
箇条書きリストは、順序付けを必要としない項目用です。番号付きリストは、決められた順序でアクションを実行するためのものです。
正しい |
正しくない |
|---|---|
この例では、3 つのグラフを使用します。 |
この例では、3 つのグラフを使用します。 |
|
|
これらの 4 つの手順は、Matplotlib の使用を開始するのに役立ちます。 |
Matplotlib の使用を開始するには、次の手順が重要です。 |
|
|
テーブル#
コンテンツを整理する際に、reStructuredText 標準で ASCII テーブルを使用します。Markdown テーブルと csv-table ディレクティブは受け入れられません。
正しい |
正しくない |
||||
|---|---|---|---|---|---|
|
| Correct | Incorrect |
| ------- | --------- |
| OK | Not OK |
|
||||
+----------+----------+
| Correct | Incorrect|
+==========+==========+
| OK | Not OK |
+----------+----------+
|
.. csv-table::
:header: "correct", "incorrect"
:widths: 10, 10
"OK ", "Not OK"
|
||||
=========== ===========
Correct Incorrect
=========== ===========
OK Not OK
=========== ===========
|
追加リソース#
このスタイル ガイドは包括的な標準ではありません。ドキュメントに貢献する方法の詳細なリファレンスについては、以下のリンクを参照してください。これらのリソースには、ドキュメントを作成するための一般的なベスト プラクティスが含まれています。
コメント#
Python コードの例では、前または同じ行にコメントがあります。
正しい
正しくない