ドキュメント¶
プロジェクトとコードのドキュメントのどちらにおいても、Pythonの開発者にとって読みやすさは最も大事なことです。 以下に紹介するいくつかのシンプルなプラクティスはあなたや他の人の多くの時間を節約することに役立つでしょう。
プロジェクトのドキュメント¶
ルートディレクトリにある README ファイルは、一般的な情報を使う人やメンテナーに伝えるものです。
生のテキストか reStructuredText や Markdown のような読みやすいマークアップで書かれている文章にして下さい。
プロジェクトやライブラリの目的を説明する部分(他にもプロジェクトで使う人に教えていたほうがいい情報)や、
ソフトウェアのソースがあるURLや、基本的なクレジット情報が数行ずつあります。
このファイルはコードの読者にとってエントリーポイントになります。
INSTALL ファイルはPythonでは必要ありません。
インストール手順は、 pip install module や python setup.py install のように一行にまとめて、
README ファイルに書かれることもあります。
LICENSE ファイルは、ソフトウェアが公開される場合にはライセンスを掲載して、指定するように常にして下さい。
TODO ファイルや README の TODO セクションはコードの開発計画を箇条書きして下さい。
CHANGELOG ファイルや README のセクションは最新版のコードの変更点の簡単な概要を書いて下さい。
プロジェクトの公開¶
プロジェクトによって、ドキュメントは以下のコンポーネントの一部、もしくは全てを含めることができます。 :
- 手順 は、製品で何ができるかの非常に簡潔な概要を掲載して下さい。 This is the thirty-second pitch for your project.
- チュートリアル は、より詳しくユースケースを掲載して下さい。 読者はプロトタイプの作業をするためにステップ・バイ・ステップで手順を追っていくでしょう。
- APIリファレンス は、コード( docstrings を参照して下さい)から生成されます。 公開されていて、利用可能なインターフェース、パラメーター、返り値などの一覧にして下さい。
- 開発者用のドキュメント は、潜在的なコントリビューター向けにすることを目的とします。 これには、コード規約とプロジェクトの一般的なデザイン戦略を含めることができます。
Sphinx¶
Sphinx は最も人気のあるPythonのドキュメント作成ツールです。 使って下さい。 HTML、LaTeX (印刷可能なPDF)、マニュアルページ、プレーンテキスト等のフォーマットで出力することができる reStructuredText マークアップ言語に変換されます。
Sphinx ドキュメントを 無料 でホスティングする すばらしい Read The Docs というものがあります。 使って下さい。ソースのレポジトリにコミットフックを設定することができるので、ドキュメントは自動的に再ビルドされます。
Note
Sphinx is famous for its API generation, but it also works well for general project documentation. This Guide is built with Sphinx and is hosted on Read The Docs
reStructuredText¶
ほとんどのPythonのドキュメントは reStructuredText で書かれています。
The reStructuredText Primer and the reStructuredText Quick Reference should help you familiarize yourself with its syntax.
コードドキュメントのアドバイス¶
コメントはコードを明確にします。
ハッシュ (#) で始めます。
Pythonでは、 docstrings はモジュール、クラス、関数に記述します。
def square_and_rooter(x):
"""Returns the square root of self times self."""
...
一般的には、 comment section of PEP 0008 (Pythonスタイルガイド)に従って下さい。
コードのコメント¶
コメントコードにトリプルクォートを使わないで下さい。 これは良いプラクティスではありません。なぜなら、
Docstrings and Magic¶
Some tools use docstrings to embed more-than-documentation behavior, such as unit test logic. Those can be nice, but you won’t ever go wrong with vanilla “here’s what this does.”
