このガイドのスタイルガイド

全てのドキュメントと同じように、 フォーマットに一貫性があることによってドキュメントをより理解してもらいやすくなります。 このガイドをより簡単に見通すことができるようにするために、 全ての貢献はこのスタイルガイドのルールに沿って適切に行われるようにして下さい。

このガイドは reStructuredText で書かれています。

Note

このガイドの一部では、このスタイルガイドにまだ即していないところもあります。

Note

レンダリングされたHTMLのページで、 著者がどのようにページを作成しているか見るために「ソースを見る」をクリックして下さい。

Relevancy

Strive to keep any contributions relevant to the purpose of The Guide.

  • Avoid including too much information on subjects that don’t directly relate to Python development.
  • Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking.
  • Cite references where needed.
  • If a subject isn’t directly relevant to Python, but useful in conjunction with Python (ex: Git, Github, Databases), reference by linking to useful resources and describe why it’s useful to Python.
  • When in doubt, ask.

見出し

見出しには以下のスタイルを使って下さい。

章のタイトル

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

ページのタイトル

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

セクションの見出し

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

サブセクションの見出し

Very Deep
~~~~~~~~~

散文

一行は78文字で折り返して下さい。 必要に応じて、折り返すことで元のテキストが読みにくくなる時は特に一行78文字を越えてもいい。

コードのサンプル

横方向のスクロールバーを出さないために、コードのサンプルは全て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

外部リンク

  • Prefer labels for well known subjects (ex: proper nouns) when linking:

    Sphinx_ is used to document Python.

.. _Sphinx: http://sphinx.pocoo.org

  • Prefer to use descriptive labels with inline links instead of leaving bare links:

    Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_

  • Avoid using labels such as “click here”, “this”, etc. preferring descriptive labels (SEO worthy) instead.

このガイドのセクションに対するリンク

To cross-reference other parts of this documentation, use the :ref: keyword and labels.

To make reference labels more clear and unique, always add a -ref suffix:

.. _some-section-ref:

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

注意書きや警告

Make use of the appropriate admonitions directives when making notes.

Notes:

.. note::
    The Hitchhiker’s Guide to the Galaxy has a few things to say
    on the subject of towels. A towel, it says, is about the most
    massively useful thing an interstellar hitch hiker can have.

Warnings:

.. warning:: DON'T PANIC

TODOs

Please mark any incomplete areas of The Guide with a todo directive. To avoid cluttering the todo-list-ref, use a single todo for stub documents or large incomplete sections.

.. todo::
    Learn the Ultimate Answer to the Ultimate Question
    of Life, The Universe, and Everything