ドキュメントへの貢献#

ドキュメントへの貢献は、pandasを使用するすべての人にとって有益です。ドキュメントの改善にご協力ください。pandasの専門家である必要はありません。実際、専門家が書いた後の方がドキュメントが悪くなっている箇所もあります。ドキュメントの内容が理解できない場合は、理解できた後に該当箇所を更新することが、次に読む人を助けるための素晴らしい方法です。pandasドキュメントに関する現在オープンになっているissueの完全なリストについては、issuesページをご覧ください。

pandasドキュメントについて#

ドキュメントは、ほぼプレーンな英語で記述するような reStructuredText で記述され、Sphinx を使用してビルドされます。Sphinxドキュメントには、reSTの優れた入門書があります。ドキュメントをより複雑に変更するには、Sphinxドキュメントも確認してください。

ドキュメントについて知っておくべきその他の重要な事項

  • pandasドキュメントは、コード自体にあるドキュメントストリングと、このフォルダーdoc/内のドキュメントの2つの部分で構成されています。

    ドキュメントストリングは、個々の関数の使用法を明確に説明する一方で、このフォルダー内のドキュメントは、トピックごとのチュートリアルのような概要と、その他の情報（新機能、インストールなど）で構成されています。

  • ドキュメントストリングは、Numpyドキュメントストリング標準に基づくpandasの規約に従います。正しいドキュメントストリングの書き方については、pandasドキュメントストリングガイドを参照してください。

  • チュートリアルでは、IPythonディレクティブ sphinx拡張機能を多用しています。このディレクティブを使用すると、ドキュメントのビルド中に実行されるコードをドキュメントに含めることができます。例:

    .. ipython:: python

    x = 2
    x**3

    は次のようにレンダリングされます。

    In [1]: x = 2

In [2]: x**3
Out[2]: 8

    ドキュメントのほぼすべてのコード例は、ドキュメントのビルド中に実行（および出力が保存）されます。このアプローチは、コード例が常に最新であることを意味しますが、ドキュメントのビルドが少し複雑になります。

  • doc/source/referenceにあるAPIドキュメントファイルには、ドキュメントストリングから自動生成されたドキュメントが格納されています。クラスの場合、どのメソッドと属性のページを自動生成するかを制御することに関して、いくつかの微妙な点があります。

    クラスには2つのautosummaryテンプレートがあります。

    1. _templates/autosummary/class.rst。クラスのすべてのパブリックメソッドと属性のページを自動的に生成する場合は、これを使用します。AttributesセクションとMethodsセクションは、numpydocによってクラスのレンダリングされたドキュメントに自動的に追加されます。例については、DataFrameを参照してください。

    2. _templates/autosummary/class_without_autosummary。ページの自動生成対象となるメソッド/属性のサブセットを選択する場合は、これを使用します。このテンプレートを使用する場合は、クラスのドキュメントストリングにAttributesセクションとMethodsセクションを含める必要があります。例については、CategoricalIndexを参照してください。

    すべてのメソッドは、doc/source/referenceにあるいずれかのドキュメントファイルのtoctreeに含める必要があります。そうしないと、Sphinxが警告を発行します。

ユーティリティスクリプトscripts/validate_docstrings.pyを使用して、APIドキュメントのcsvサマリーを取得できます。また、特定のクラス、関数、またはメソッドのドキュメントストリングにある一般的なエラーを検証することもできます。サマリーは、doc/source/reference内のファイルでドキュメント化されているメソッドのリスト（APIリファレンスページを生成するために使用される）と、実際のパブリックメソッドを比較します。これにより、実際にはクラスメソッドではないdoc/source/referenceでドキュメント化されているメソッドと、doc/source/referenceでドキュメント化されていない既存のメソッドが識別されます。

pandasのドキュメントストリングの更新#

単一の関数またはメソッドのドキュメントストリングを改善する場合、必ずしも完全なドキュメントをビルドする必要はありません（次のセクションを参照）。ただし、ドキュメントストリング（たとえば、DataFrame.meanメソッドの場合）をチェックするスクリプトがあります。

python scripts/validate_docstrings.py pandas.DataFrame.mean

このスクリプトは、存在する場合はいくつかの書式設定エラーを示し、ドキュメントストリングに含まれている例を実行してテストします。ドキュメントストリングの書式設定方法の詳細なガイドについては、pandasドキュメントストリングガイドを確認してください。

ドキュメントストリング（「doctest」）内の例は、決定論的な方法で提示された出力を返し、ユーザーがコピーして実行できる有効なPythonコードである必要があります。これは上記のスクリプトで確認でき、Travisでもテストされます。doctestの失敗は、PRのマージの妨げになります。doctestを合格させるためのヒントとコツについては、ドキュメントストリングガイドの例セクションを確認してください。

ドキュメントストリングの更新を含むPRを作成するときは、githubのコメントに検証スクリプトの出力を投稿することをお勧めします。

pandasドキュメントのビルド方法#

要件#

まず、pandasをビルドできるように開発環境が必要です（開発環境の作成に関するドキュメントを参照してください）。

ドキュメントのビルド#

では、ドキュメントをどのようにビルドするのでしょうか？コンソールでローカルのdoc/ディレクトリに移動し、次を実行します。

python make.py html

次に、doc/build/html/フォルダーにHTML出力を見つけることができます。

ドキュメントを初めてビルドするときは、すべてのコード例を実行し、生成されたすべてのドキュメントストリングページをビルドする必要があるため、かなり時間がかかります。後続の呼び出しでは、sphinxは変更されたページのみをビルドしようとします。

完全なクリーンビルドを実行する場合は、次のようにします。

python make.py clean
python make.py html

make.pyにドキュメントの単一のセクションのみをコンパイルするように指示することで、変更を確認するためのターンアラウンド時間を大幅に短縮できます。

# omit autosummary and API section
python make.py clean
python make.py --no-api

# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst

# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join

# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew

比較として、完全なドキュメントビルドには15分かかる場合がありますが、単一のセクションには15秒かかる場合があります。変更した部分のみを処理する後続のビルドは、より高速になります。

ビルドは、ドキュメントのビルドを高速化するために、マシンで使用可能なコア数を自動的に使用します。これをオーバーライドできます。

python make.py html --num-jobs 4

Webブラウザーで次のファイルを開いて、ビルドしたばかりの完全なドキュメントdoc/build/html/index.htmlを表示します。

そして、新しく改善されたドキュメントを見る満足感を得られるでしょう！

mainブランチのドキュメントのビルド#

プルリクエストがpandasのmainブランチにマージされると、ドキュメントの主要部分もTravis-CIによってビルドされます。これらのドキュメントはこちらでホストされています。また、継続的インテグレーションセクションも参照してください。

変更のプレビュー#

プルリクエストが送信されると、GitHub Actionsがドキュメントを自動的にビルドします。ビルドされたサイトを表示するには

  1. CI / Web and docsチェックが完了するのを待ちます。

  2. その横にある詳細をクリックします。

  3. 「Artifacts」ドロップダウンから、「docs」または「website」をクリックして、サイトをZIPファイルとしてダウンロードします。