Pythonコードの文書化:完全なガイド

Pythonコードの文書化:完全なガイド

Pythonコードの文書化に関する完全なガイドへようこそ。 あなたが小さなスクリプトであれ大規模なプロジェクトであれ、初心者であろうと熟練したPythonistaであろうと、このガイドはあなたが知る必要があるすべてをカバーします。

このチュートリアルは4つの主要なセクションに分かれています。

  1. * link:#why-documenting-your-code-is-so-important [なぜコードをドキュメント化することがとても重要なのか]:*ドキュメントの紹介とその重要性

  2. * link:#commenting-vs.-documenting-code [コメントvs. ドキュメント化コード]:*コメントとドキュメント化の主な違いの概要、およびコメントを使用する適切な時間と方法

  3. * link:#documenting-your-python-code-base [Docstringsを使用したPythonコードベースのドキュメント化]:*クラス、クラスメソッド、関数、モジュール、パッケージ、およびスクリプトのdocstringsの詳細と、何をすべきかそれぞれの中に見つかりました

  4. * link:#documenting-your-python-projects [Pythonプロジェクトのドキュメント化]:* Pythonプロジェクトに必要な要素とその内容

このチュートリアルを最初から最後までお読みになるか、興味のあるセクションにジャンプしてください。 両方の方法で動作するように設計されました。

コードを文書化することが非常に重要な理由

このチュートリアルを読んでいる方は、コードを文書化することの重要性を既にご存じでしょう。 しかし、そうでない場合は、最近のPyConでGuidoが私に言及したことを引用させてください。

_ _ 「コードは書かれているよりも読むことが多いです。」

Guido van Rossum _ _

コードを記述するとき、ユーザーと開発者(自分を含む)の2つの主要な対象者向けに記述します。 両方の聴衆も同様に重要です。 あなたが私のような人なら、おそらく古いコードベースを開いて、「この世界で私は何を考えていたのか?」独自のコードの読み取りに問題がある場合は、ユーザーや他の開発者がコードを使用したり、コードに貢献しようとしたときにどのような問題が発生するかを想像してください。

逆に、あなたはPythonで何かをしたいという状況に出くわし、仕事を成し遂げるすばらしいライブラリのように見えるものを見つけたと確信しています。 ただし、ライブラリの使用を開始するときは、例、記事、または特定の操作方法に関する公式ドキュメントを探しており、すぐに解決策を見つけることができません。

検索した後、ドキュメントが欠けているか、さらに悪いことに完全に欠けていることに気付くようになります。 これは、コードがどれほど優れていても効率的であっても、ライブラリの使用を思いとどまらせるイライラ感です。 Daniele Procidaは、この状況を最もよく要約しました。

_ _ 「ソフトウェアがどれほど優れているかは関係ありません。ドキュメントが十分でない場合、人々はそれを使用しないからです。」

Daniele Procida _ _ __

このガイドでは、最小のスクリプトから最大のPythonプロジェクトまでPythonコードを適切に文書化する方法を一から学び、ユーザーがプロジェクトを使用したり貢献したりするのに不満を感じないようにします。

コメント対 文書化コード

Pythonコードをドキュメント化する方法に入る前に、ドキュメント化とコメントを区別する必要があります。

一般的に、コメントとは開発者への/開発者向けのコードの説明です。 主な対象読者は、Pythonコードのメンテナーと開発者です。 よく書かれたコードと併せて、コメントは読者がコードとその目的と設計をよりよく理解するように導くのに役立ちます。

_ _ 「コードはその方法を示しています。コメントが理由を教えてくれます。」

Jeff Atwood(別名コーディングホラー) _ _

ドキュメント化コードは、その使用と機能をユーザーに説明しています。 開発プロセスには役立ちますが、主な対象読者はユーザーです。 次のセクションでは、コードをコメントする方法とタイミングについて説明します。

コメントコードの基本

コメントは、ポンド記号( )を使用してPythonで作成され、数文以内の短いステートメントである必要があります。 以下に簡単な例を示します。

def hello_world():
    # A simple comment preceding a simple print statement
    print("Hello World")

PEP 8によれば、コメントの最大長は72文字です。 これは、プロジェクトで最大行長を推奨の80文字より長く変更した場合にも当てはまります。 コメントがコメントの文字数制限よりも大きくなる場合、コメントに複数行を使用するのが適切です。

def hello_long_world():
    # A very long statement that just goes on and on and on and on and
    # never ends until after it's reached the 80 char limit
    print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

コードにコメントを追加すると、https://en.wikipedia.org/wiki/Comment_(computer_programming)#Uses [複数の目的を含む]を提供します。

  • *計画とレビュー:*コードの新しい部分を開発する場合、最初にコメントを使用して、コードのそのセクションを計画または概説することが適切な場合があります。 実際のコーディングが実装され、レビュー/テストされたら、これらのコメントを忘れずに削除してください。

# First step
# Second step
# Third step
  • *コードの説明:*コメントを使用して、コードの特定のセクションの意図を説明できます。

# Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.
  • *アルゴリズムの説明:*アルゴリズム、特に複雑なアルゴリズムを使用する場合、アルゴリズムの仕組みやコード内での実装方法を説明すると便利です。 特定のアルゴリズムが別のアルゴリズムよりも選択された理由を説明することも適切です。

# Using quick sort for performance gains
  • *タグ付け:*タグ付けの使用を使用して、既知の問題または改善領域があるコードの特定のセクションにラベルを付けることができます。 いくつかの例は、「+ BUG 」、「 FIXME 」、および「 TODO +」です。

# TODO: Add condition for when val is None

コードへのコメントは簡潔かつ焦点を合わせてください。 可能な限り長いコメントを使用しないでください。 さらに、https://blog.codinghorror.com/when-good-comments-go-bad/[Jeff Atwoodによる提案]として、次の4つの重要なルールを使用する必要があります。

  1. コメントは可能な限り記述されるコードの近くに置いてください。 記述コードの近くにないコメントは、読者を苛立たせ、更新が行われたときに簡単に見逃されます。

  2. 複雑なフォーマット(テーブルやASCII数字など)を使用しないでください。 複雑な書式設定は、気が散るコンテンツにつながり、時間の経過とともに維持することが困難になる場合があります。

  3. 冗長な情報を含めないでください。 コードの読者がプログラミングの原則と言語構文の基本的な理解を持っていると仮定します。

  4. コード自体をコメントするように設計します。 コードを理解する最も簡単な方法は、コードを読むことです。 明確で理解しやすい概念を使用してコードを設計すると、読者は意図をすばやく概念化できます。

コメントは、ソフトウェアの目的と設計を理解する上で役立つように、読者自身(読者自身を含む)用に設計されていることを忘れないでください。

型ヒントを介したコードのコメント(Python 3.5+)

型ヒントはPython 3.5に追加され、コードの読者を支援する追加の形式です。 実際、ジェフの4番目の提案は、上から次のレベルへと進みます。 開発者は、コメントなしでコードの一部を設計および説明できます。 以下に簡単な例を示します。

def hello_name(name: str) -> str:
    return(f"Hello {name}")

型のヒントを調べると、関数が入力 `+ name `が型 ` str `または文字列であることを期待していることがすぐにわかります。 関数の期待される出力は、タイプ ` str +`または文字列でもあることもわかります。 型のヒントはコメントを減らすのに役立ちますが、プロジェクトドキュメントを作成または更新するときに余分な作業が必要になる場合があることを考慮してください。

タイプヒンティングとタイプチェックの詳細については、https://www.youtube.com/watch?v = 2xWhaALHTvU [Dan Baderによって作成されたこのビデオ]をご覧ください。

Docstringsを使用してPythonコードベースを文書化する

コメントについて学習したので、Pythonコードベースの文書化について詳しく見ていきましょう。 このセクションでは、ドキュメント文字列とそれらをドキュメントに使用する方法について学習します。 このセクションは、さらに次のサブセクションに分かれています。

  1. * link:#docstrings-background [Docstrings Background]: Python内でのdocstringsの内部​​動作の背景 . link:#docstring-types [Docstring Types]:*さまざまなdocstring“ types”(関数、クラス、クラスメソッド、モジュール、パッケージ、およびスクリプト)

  2. * link:#docstring-formats [Docstring Formats]:*さまざまなdocstring“ formats”(Google、NumPy/SciPy、reStructured Text、およびEpytext)

Docstringsの背景

Pythonコードの文書化は、すべてdocstringを中心にしています。 これらは組み込みの文字列であり、正しく構成されていれば、プロジェクトのドキュメントでユーザーと自分自身を支援できます。 Pythonには、docstringの他に、オブジェクトdocstringをコンソールに出力する組み込み関数 `+ help()+`もあります。 以下に簡単な例を示します。

>>>

>>> help(str)
Help on class str in module builtins:

class str(object)
 |  str(object='') -> str
 |  str(bytes_or_buffer[, encoding[, errors]]) -> str
 |
 |  Create a new string object from the given object. If encoding or
 |  errors are specified, then the object must expose a data buffer
 |  that will be decoded using the given encoding and error handler.
 |  Otherwise, returns the result of object.__str__() (if defined)
 |  or repr(object).
 |  encoding defaults to sys.getdefaultencoding().
 |  errors defaults to 'strict'.
 # Truncated for readability

この出力はどのように生成されますか? Pythonのすべてはオブジェクトなので、 `+ dir()+`コマンドを使用してオブジェクトのディレクトリを調べることができます。 それをして、何が見つかるか見てみましょう:

>>>

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

そのディレクトリ出力内には、興味深いプロパティ、「+ doc +」があります。 そのプロパティを調べると、次のことがわかります。

>>>

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

ほら! オブジェクト内のdocstringが保存されている場所を見つけました。 これは、そのプロパティを直接操作できることを意味します。 ただし、ビルトインには制限があります。

>>>

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'str'

その他のカスタムオブジェクトは操作できます。

def say_hello(name):
    print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"

>>>

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

Pythonには、docstringの作成を簡素化するもう1つの機能があります。 `+ doc `プロパティを直接操作する代わりに、オブジェクトのすぐ下に文字列リテラルを戦略的に配置すると、自動的に ` doc +`値が設定されます。 上記と同じ例で起こることは次のとおりです。

def say_hello(name):
    """A simple function that says hello... Richie style"""
    print(f"Hello {name}, is it me you're looking for?")

>>>

>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
    A simple function that says hello... Richie style

そこに行きます! これで、docstringの背景が理解できました。 次に、さまざまな種類のdocstringとそれらに含まれる情報について学習します。

Docstringタイプ

Docstringの規則は、https://www.python.org/dev/peps/pep-0257/[PEP 257]で説明されています。 その目的は、オブジェクトの概要をユーザーに提供することです。 保守しやすいように簡潔に保つ必要がありますが、新規ユーザーが目的と文書化されたオブジェクトの使用方法を理解できるように、十分に精巧に記述する必要があります。

すべての場合において、docstringsはトリプルダブルクォート( `+" "" + `)文字列形式を使用する必要があります。 これは、docstringが複数行であるかどうかに関係なく実行する必要があります。 最低限、docstringは、記述している内容の簡単な要約であり、1行に含める必要があります。

"""This is a quick summary line used as a description of the object."""

複数行のdocstringを使用して、要約を超えてオブジェクトをさらに詳しく説明します。 すべての複数行のdocstringには次の部分があります。

  • 1行の要約行

  • 要約に続く空白行

  • docstringのさらなる詳細

  • 別の空白行

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""

# Notice the blank line above. Code should continue on this line.

すべてのdocstringは、コメントと同じ最大文字長(72文字)でなければなりません。 文書文字列は、さらに3つの主要なカテゴリに分類できます。

  • * Class Docstrings:*クラスおよびクラスメソッド

  • *パッケージおよびモジュールのドキュメント文字列:*パッケージ、モジュール、および関数

  • *スクリプトDocstrings:*スクリプトと関数

クラスDocstrings

クラスDocstringsは、クラス自体とクラスメソッドに対して作成されます。 docstringは、1つのレベルでインデントされたクラスまたはクラスメソッドの直後に配置されます。

class SimpleClass:
    """Class docstrings go here."""

    def say_hello(self, name: str):
        """Class method docstrings go here."""

        print(f'Hello {name}')

クラスdocstringsには次の情報が含まれている必要があります。

  • その目的と動作の簡単な要約

  • パブリックメソッドと簡単な説明

  • すべてのクラスプロパティ(属性)

  • クラスがサブクラス化されることを意図している場合、サブクラス化のためのインターフェースに関連するもの

クラスコンストラクターのパラメーターは、 `+ init +`クラスメソッドdocstring内に文書化する必要があります。 個々のメソッドは、個々のdocstringを使用して文書化する必要があります。 クラスメソッドのdocstringsには次が含まれている必要があります。

  • メソッドの概要と使用方法の簡単な説明

  • キーワード引数を含む、渡される引数(必須およびオプション)

  • オプションと見なされる引数またはデフォルト値を持つ引数にラベルを付けます

  • メソッドの実行時に発生する副作用

  • 発生する例外

  • メソッドをいつ呼び出せるかに関する制限

動物を表すデータクラスの簡単な例を見てみましょう。 このクラスには、いくつかのクラスプロパティ、インスタンスプロパティ、 + init +、および単一のインスタンスメソッドが含まれます。

class Animal:
    """
    A class used to represent an Animal

    ...

    Attributes
    ----------
    says_str : str
        a formatted string to print out what the animal says
    name : str
        the name of the animal
    sound : str
        the sound that the animal makes
    num_legs : int
        the number of legs the animal has (default 4)

    Methods
    -------
    says(sound=None)
        Prints the animals name and what sound it makes
    """

    says_str = "A {name} says {sound}"

    def __init__(self, name, sound, num_legs=4):
        """
        Parameters
        ----------
        name : str
            The name of the animal
        sound : str
            The sound the animal makes
        num_legs : int, optional
            The number of legs the animal (default is 4)
        """

        self.name = name
        self.sound = sound
        self.num_legs = num_legs

    def says(self, sound=None):
        """Prints what the animals name is and what sound it makes.

        If the argument `sound` isn't passed in, the default Animal
        sound is used.

        Parameters
        ----------
        sound : str, optional
            The sound the animal makes (default is None)

        Raises
        ------
        NotImplementedError
            If no sound is set for the animal or passed in as a
            parameter.
        """

        if self.sound is None and sound is None:
            raise NotImplementedError("Silent Animals are not supported!")

        out_sound = self.sound if sound is None else sound
        print(self.says_str.format(name=self.name, sound=out_sound))
パッケージとモジュールのドキュメント文字列

パッケージdocstringsは、パッケージの `+ init 。py +`ファイルの先頭に配置する必要があります。 このdocstringは、パッケージによってエクスポートされるモジュールとサブパッケージをリストする必要があります。

モジュールのドキュメント文字列は、クラスのドキュメント文字列に似ています。 文書化されているクラスとクラスメソッドの代わりに、モジュールとその中にあるすべての関数になりました。 モジュールのdocstringは、インポートの前でもファイルの先頭に配置されます。 モジュールのdocstringには次が含まれている必要があります。

  • モジュールの簡単な説明とその目的

  • モジュールによってエクスポートされたクラス、例外、関数、およびその他のオブジェクトのリスト

モジュール関数のdocstringには、クラスメソッドと同じアイテムを含める必要があります。

  • 機能の概要と用途

  • キーワード引数を含む、渡される引数(必須およびオプション)

  • オプションと見なされる引数にラベルを付けます

  • 関数の実行時に発生する副作用

  • 発生する例外 *関数をいつ呼び出せるかに関する制限

スクリプトDocstrings

スクリプトは、コンソールから実行される単一のファイル実行可能ファイルと見なされます。 スクリプトのドキュメント文字列はファイルの先頭に配置され、ユーザーがスクリプトの使用方法を十分に理解できるように十分に文書化する必要があります。 ユーザーがパラメーターを誤って渡したり、 `+ -h +`オプションを使用したりすると、「使用」メッセージに使用できるはずです。

`+ argparse `を使用する場合、 ` argparser.parser.add_argument `関数の ` help `パラメーター内で正しく文書化されていると仮定して、パラメーター固有の文書化を省略できます。 ` argparse.ArgumentParser `のコンストラクター内の ` description `パラメーターに ` doc `を使用することをお勧めします。 ` argparse +`の使用方法の詳細については、https://realpython.com/comparing-python-command-line-parsing-libraries-argparse-docopt-click/[コマンドライン解析ライブラリ]のチュートリアルをご覧ください。他の一般的なコマンドラインパーサー。

最後に、スクリプトの実行に必要なパッケージをユーザーが認識できるように、カスタムまたはサードパーティのインポートをdocstrings内にリストする必要があります。 スプレッドシートの列ヘッダーを簡単に印刷するために使用されるスクリプトの例を次に示します。

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

   * get_spreadsheet_cols - returns the column headers of the file
    * main - the main function of the script
"""

import argparse

import pandas as pd


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        'input_file',
        type=str,
        help="The spreadsheet file to pring the columns of"
    )
    args = parser.parse_args()
    get_spreadsheet_cols(args.input_file, print_cols=True)


if __name__ == "__main__":
    main()

Docstringフォーマット

このチュートリアルで示した例全体を通して、共通の要素( + Arguments ++ Returns +、および + Attributes +)を使用した特定の書式設定があることに気づいたかもしれません。 docstringパーサーを支援するために使用できる特定のdocstrings形式があり、ユーザーは使い慣れた既知の形式を持っています。 このチュートリアルの例で使用されているフォーマットは、NumPy/SciPyスタイルのdocstringです。 最も一般的な形式のいくつかは次のとおりです。

Formatting Type Description Supported by Sphynx Formal Specification

Google docstrings

Google’s recommended form of documentation

Yes

No

reStructured Text

Official Python documentation standard; Not beginner friendly but feature rich

Yes

Yes

NumPy/SciPy docstrings

NumPy’s combination of reStructured and Google Docstrings

Yes

Yes

Epytext

A Python adaptation of Epydoc; Great for Java developers

Not officially

Yes

docstring形式の選択はユーザー次第ですが、ドキュメント/プロジェクト全体で同じ形式を使用する必要があります。 以下は、各ドキュメント形式の外観を理解するための各タイプの例です。

Google Docstringsの例
"""Gets and prints the spreadsheet's header columns

Args:
    file_loc (str): The file location of the spreadsheet
    print_cols (bool): A flag used to print the columns to the console
        (default is False)

Returns:
    list: a list of strings representing the header columns
"""
再構築されたテキストの例
"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
    (default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""
NumPy/SciPy Docstringsの例
"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
    The file location of the spreadsheet
print_cols : bool, optional
    A flag used to print the columns to the console (default is False)

Returns
-------
list
    a list of strings representing the header columns
"""
Epytextの例
"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
    (default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

Pythonプロジェクトの文書化

Pythonプロジェクトには、あらゆる種類の形状、サイズ、目的があります。 プロジェクトを文書化する方法は、特定の状況に適合する必要があります。 プロジェクトのユーザーが誰になるかを念頭に置き、ニーズに適応してください。 プロジェクトの種類に応じて、ドキュメントの特定の側面が推奨されます。 プロジェクトとそのドキュメントの一般的なレイアウトは次のとおりです。

project_root/
│
├── project/ # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

通常、プロジェクトは、プライベート、共有、およびパブリック/オープンソースの3つの主要なタイプに分類できます。

プライベートプロジェクト

プライベートプロジェクトは、個人使用のみを目的としたプロジェクトであり、通常は他のユーザーや開発者と共有されません。 これらのタイプのプロジェクトについては、ドキュメントは非常に軽快です。 必要に応じて追加する推奨部品がいくつかあります。

  • * Readme:*プロジェクトの概要とその目的。 プロジェクトのインストールまたは操作に関する特別な要件を含めます。

  • * + examples.py +:*プロジェクトの使用方法の簡単な例を提供するPythonスクリプトファイル。

プライベートプロジェクトが個人的に意図されたものであっても、ユーザーとみなされることを忘れないでください。 混乱を招く可能性のあるものについて考え、コメント、docstring、またはreadmeのいずれかでそれらをキャプチャするようにしてください。

共有プロジェクト

共有プロジェクトとは、プロジェクトの開発および/または使用において、他の少数の人々と協力するプロジェクトです。 プロジェクトの「顧客」またはユーザーは引き続き自分自身であり、プロジェクトを使用する限られた少数のユーザーです。

ドキュメンテーションは、主にプロジェクトへの新規メンバーの参加を支援したり、プロジェクトへの新しい変更の貢献者/ユーザーに警告するために、プライベートプロジェクトに必要なものよりも少し厳密でなければなりません。 プロジェクトに追加する推奨部品の一部は次のとおりです。

  • * Readme:*プロジェクトの概要とその目的。 プロジェクトをインストールまたは操作するための特別な要件を含めます。 さらに、以前のバージョン以降の主要な変更を追加します。

  • * + examples.py +:*プロジェクトの使用方法の簡単な例を提供するPythonスクリプトファイル。

  • *貢献方法:*これには、プロジェクトへの新しい貢献者が貢献を開始する方法が含まれている必要があります。

パブリックおよびオープンソースプロジェクト

パブリックプロジェクトおよびオープンソースプロジェクトは、多数のユーザーグループと共有することを目的としたプロジェクトであり、大規模な開発チームが関与する可能性があります。 これらのプロジェクトは、プロジェクト自体の実際の開発と同様に、プロジェクトのドキュメントを優先する必要があります。 プロジェクトに追加する推奨部品の一部は次のとおりです。

  • * Readme:*プロジェクトの概要とその目的。 プロジェクトをインストールまたは操作するための特別な要件を含めます。 さらに、以前のバージョン以降の主要な変更を追加します。 最後に、プロジェクトの詳細なドキュメント、バグ報告、その他の重要な情報へのリンクを追加します。 Dan Baderは、readmeに何を含めるべきかについてhttps://dbader.org/blog/write-a-great-readme-for-your-github-project [素晴らしいチュートリアル]をまとめました。

  • *貢献方法:*これには、プロジェクトへの新しい貢献者がどのように役立つかを含める必要があります。 これには、新機能の開発、既知の問題の修正、ドキュメントの追加、新しいテストの追加、または問題の報告が含まれます。

  • *行動規範:*ソフトウェアを開発または使用する際に、他の貢献者がお互いをどのように扱うべきかを定義します。 また、このコードが壊れた場合に何が起こるかについても述べています。 Githubを使用している場合は、推奨される文言で行動規範https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/[template]を生成できます。 特にオープンソースプロジェクトの場合、これを追加することを検討してください。

  • *ライセンス:*プロジェクトで使用しているライセンスを説明するプレーンテキストファイル。 特にオープンソースプロジェクトの場合、これを追加することを検討してください。

  • * docs:*詳細なドキュメントを含むフォルダー。 次のセクションでは、何を含めるべきか、およびこのフォルダーの内容を整理する方法について詳しく説明します。

`+ docs +`フォルダーの4つのメインセクション

Daniele Procidaはすばらしいhttps://www.youtube.com/watch?v=azf6yzuJt54[PyCon 2017トーク]とその後のhttps://www.divio.com/en/blog/documentation/[ブログ投稿] Pythonのドキュメント化について説明しましたプロジェクト。 彼は、あなたの仕事に集中するのを助けるために、すべてのプロジェクトが以下の4つの主要なセクションを持つべきであると述べます:

  • チュートリアル:プロジェクトを完了するための一連の手順(または有意義な演習)を読者が手で取るレッスン。 ユーザーの学習を対象としています。

  • ハウツーガイド:一般的な問題(問題指向のレシピ)を解決するために必要な手順を読者に案内するガイド。

  • 参考文献:特定のトピックを明確にし、説明する説明。 理解に向けて。

  • 説明:機械の技術的な説明とその操作方法(主要なクラス、機能、APIなど)。 百科事典の記事を考えてください。

次の表は、これらのすべてのセクションが相互にどのように関連しているか、およびそれらの全体的な目的を示しています。

Most Useful When We’re Studying Most Useful When We’re Coding

Practical Step

Tutorials

How-To Guides

Theoretical Knowledge

Explanation

Reference

最終的には、ユーザーが質問に対する回答にアクセスできるようにする必要があります。 このようにプロジェクトを整理することで、これらの質問に簡単に答えることができ、すばやくナビゲートできる形式で作成できます。

ドキュメント作成ツールとリソース

コード、特に大規模なプロジェクトを文書化することは困難です。 ありがたいことに、いくつかのツールと参考資料があります。

Tool Description

Sphinx

A collection of tools to auto-generate documentation in multiple formats

Epydoc

A tool for generating API documentation for Python modules based on their docstrings

Read The Docs

Automatic building, versioning, and hosting of your docs for you

Doxygen

A tool for generating documentation that supports Python as well as multiple other languages

MkDocs

A static site generator to help build project documentation using the Markdown language

pycco

A “quick and dirty” documentation generator that displays code and documentation side by side. Check out our tutorial on how to use it for more info.

これらのツールに加えて、プロジェクトをドキュメント化するときに役立つ追加のチュートリアル、ビデオ、および記事があります。

時々、学ぶための最良の方法は他人を真似ることです。 ドキュメントを上手に使用するプロジェクトの素晴らしい例を次に示します。

  • * Django:* Docs(https://github.com/django/django/tree/master/docs [ソース])

  • リクエスト: Docs(https://github.com/requests/requests/tree/master/docs [ソース])

  • クリック: Docs(https://github.com/pallets/click/tree/master/docs [ソース])

  • パンダ: Docs(https://github.com/pandas-dev/pandas/tree/master/doc [ソース])

どこから始めますか?

プロジェクトのドキュメントは簡単に進行します:

  1. ドキュメントなし

  2. いくつかのドキュメント

  3. 完全なドキュメント

  4. 良いドキュメント

  5. 素晴らしいドキュメント

ドキュメントの次に進むべき場所がわからない場合は、上記の進行に関連してプロジェクトの現在の場所を確認してください。 ドキュメントはありますか? そうでない場合は、そこから開始します。 いくつかのドキュメントはあるが、主要なプロジェクトファイルの一部が欠落している場合は、それらを追加して始めてください。

最終的に、コードの文書化に必要な作業量に落胆したり、圧倒されたりしないでください。 コードのドキュメント化を開始すると、継続しやすくなります。 質問がある場合やソーシャルメディアでReal Python Teamに連絡する場合は、お気軽にコメントしてください。