ドキュメントへの貢献#

ドキュメントへの貢献は、pandas を利用するすべての人に利益をもたらします。私たちは、ドキュメントの改善にご協力いただくことを奨励しており、そのために pandas の専門家である必要はありません！実際、専門家によって書かれたために質が低下したドキュメントのセクションも存在します。ドキュメントの内容が理解できない場合、それを理解した後に該当するセクションを更新することは、次に利用する人の助けになる素晴らしい方法です。現在、Pandas ドキュメントに関して開いているすべての問題のリストについては、issue ページをご覧ください。

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

ドキュメントはreStructuredTextで書かれており、これはほぼ平易な英語で書くことに近く、Sphinxを使用して構築されます。Sphinx Documentationには、reSTの優れた入門があります。より複雑なドキュメントの変更を行う場合も、Sphinx ドキュメントを参照してください。

ドキュメントに関するその他の重要な情報

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

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

  • ドキュメント文字列は、Numpy Docstring Standardに基づいて、pandas の慣習に従っています。正しいドキュメント文字列の書き方に関する詳細な手順については、pandas ドキュメント文字列ガイドに従ってください。

  • チュートリアルでは、IPython directive 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 Reference ページの生成に使用されます）で記述されているメソッドのリストと、実際の公開メソッドのリストも比較します。これにより、doc/source/reference で記述されているが実際にはクラスメソッドではないメソッドや、doc/source/reference で記述されていない既存のメソッドを特定できます。

pandas ドキュメント文字列の更新#

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

python scripts/validate_docstrings.py pandas.DataFrame.mean

このスクリプトは、もしあればいくつかの書式設定エラーを指摘し、ドキュメント文字列に含まれる例を実行およびテストします。ドキュメント文字列の書式設定方法の詳細については、pandas ドキュメント文字列ガイドを確認してください。

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

ドキュメント文字列の更新を含む PR を行う場合、検証スクリプトの出力を GitHub のコメントに投稿すると良いでしょう。

pandas ドキュメントの構築方法#

要件#

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

ドキュメントの構築#

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

python make.py html

すると、HTML 出力はフォルダ doc/build/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

ビルドしたばかりのドキュメント全体を表示するには、ウェブブラウザで次のファイルを開きます doc/build/html/index.html。

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

メインブランチのドキュメントの構築#

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

変更のプレビュー#

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

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

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

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