ガイドスタイルガイド¶

すべてのドキュメンテーションと同様に、一貫したフォーマットを使用すると、ドキュメントがわかりやすくなります。ガイドをダイジェストしやすくするために、すべての寄稿はこのスタイルガイドのルールの中に適切に収まる必要があります。

ガイドは reStructuredText と書かれています。

注釈

ガイドの一部がこのスタイルガイドとまだ一致していない可能性があります。これらの部分をガイドスタイルガイドと同期して更新してください。

注釈

レンダリングされたHTMLのどのページでも、「ソースの表示」をクリックして、著者がページのスタイルをどのようにしているかを見ることができます。

見出し¶

見出しには次のスタイルを使用します。

章のタイトル:

#########
Chapter 1
#########

ページタイトル:

===================
Time is an Illusion
===================

セクション見出し:

Lunchtime Doubly So
-------------------

サブセクション見出し:

Very Deep
~~~~~~~~~

散文¶

テキスト行を78文字で囲みます。必要に応じて、行が78文字を超える場合があります。特に、折り返しをするとソーステキストを読みにくくする可能性があります。

シリアルカンマ（オックスフォードカンマとしても知られています）の使用は100％非オプションです。シリアルカンマがないコンテンツを提出しようとすると、全体の判断が不足し完了するため、このプロジェクトは永久に追放することになります。

追放？それは冗談ですか？うまくいけば、私たちは決して見つけ出す必要はありません。

コード例¶

水平スクロールバーを避けるには、すべてのコード例を70文字で囲みます。

コマンドラインの例:

.. code-block:: console

    $ run command --help
    $ ls ..

各行の前に $ 接頭辞を必ず付けてください。

Pythonインタプリタの例:

Label the example::

.. code-block:: python

    >>> import this

Pythonの例:

Descriptive title::

.. code-block:: python

    def get_answer():
        return 42

外部リンク¶

リンク時によく知られている主題（例：固有名詞）のラベルを優先する:
```
SphinxはPythonを文書化するために使用されます。
```

空のリンクを残す代わりに、インラインリンクの説明ラベルを使用することをお勧めします。
```
Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
```

記述ラベル（SEOにふさわしい）を好む代わりに、「ここをクリック」、「これ」などのラベルを使用しないでください。

ガイドのセクションへのリンク¶

このドキュメントの他の部分を相互参照するには、 :ref: キーワードとラベルを使用してください。

参照ラベルをより明確かつユニークにするには、常に -ref 接尾辞を追加します:

.. _some-section-ref:

Some Section
------------

注釈と警告¶

注釈を作るときは、適切な警告指令を利用してください。

注釈:

.. note::
    銀河ヒッチハイク・ガイドには、タオルのテーマについていくつかのことが言及されています。 タオルは、星間のヒッチハイカーが持つことができる最も大規模で有用なものであると言います。

警告:

.. warning:: パニックに陥らないでください

TODOs¶

ガイドの不完全な部分は、 todo directive でマークしてください。 todo-list-ref が乱雑にならないようにするには、スタブドキュメントや大規模な不完全セクションに対しては単一の todo を使います。

.. todo::
    生命、宇宙、そしてすべての究極の質問への究極の答えを学ぶ

ガイドスタイルガイド¶

関連性¶

見出し¶

散文¶

コード例¶

外部リンク¶

ガイドのセクションへのリンク¶

注釈と警告¶

TODOs¶

アップデートを入手する

オライリー・ブック

その他のプロジェクト

翻訳

目次

Related Topics