Pythonパッケージのユーザー向けドキュメントを作成する#
ユーザー向けPythonパッケージドキュメントのコアコンポーネント#
以下では、ドキュメントを2つのタイプに大別します。
ユーザー向け文書 は、パッケージ内のツールがワークフローで広く使用される方法を説明する文書を指します。 APIドキュメント は、コード内の関数、クラス、メソッド、属性のドキュメントを指し、より細かいレベルで書かれています。 このドキュメントは、ユーザーが help(function-name) とタイプしたときに表示されるものです。
Pythonパッケージのユーザー向けドキュメントには、いくつかのコアコンポーネントを含めるべきです。
ドキュメントウェブサイト: これは、誰かがあなたのパッケージを使うのを助ける、読みやすいドキュメンテーションのことです。 このドキュメンテーションは、ユーザがあなたのパッケージをインストールし、使うのを助けるものでなければなりません。
短いチュートリアル: ユーザー向けのドキュメントには、 パッケージのコア機能を紹介する 短いチュートリアル も含めるべきです。
パッケージコード/APIドキュメント: パッケージの関数、クラス、メソッド、属性（API）もドキュメント化されるべきです。 APIドキュメントは、あなたのコードにある docstrings から生成することができます。 理想的には、Pythonパッケージ内のすべてのユーザー向けの関数、クラス、メソッドのdocstringがあることです。 コードドキュメンテーションとdocstringについてはこちらで詳しく説明します。
使いやすい文書を書く#
ユーザー向けのドキュメントは、閲覧しやすいウェブサイトで公開されるべきである。 ドキュメントは、ユーザーが開発者や専門家レベルのプログラマーではないことを念頭に置いて書かれるべきです。 むしろ、ドキュメントで使用する言語は、高度な技術的なものであってはなりません。
ドキュメンテーションの言語を、より多くの読者が理解できるようにする:
可能な限り、技術用語や専門用語を定義する。
高校生レベルの読者を想定して指示を書く。
あなたのパッケージの使い始めをサポートする、ステップ・バイ・ステップのコード例、チュートリアル、またはヴィネットを含めてください。
優れたオープンソース・ドキュメントのランディングページの4つの要素#
ユーザーが必要なものをすぐに見つけられるように、パッケージのランディングページに以下の要素へのクイックリンクを追加することを検討してください:
開始: このセクションは、あなたのパッケージをインストールするためのクイックスタート をユーザーに提供するものです。 パッケージの使い方の小さな例もここにあると良いでしょう。 または、便利なチュートリアルへのリンクを、スタートセクションに置くこともできます。
About: プロジェクトについて、その目標と機能を説明してください。
Community: どのように手伝ったり、参加したりするかについての説明。 このセクションには、issue (ユーザーに質問できるようにしている場合) や GitHub リポジトリのディスカッションへのリンクが含まれます。 このセクションには、あなたのパッケージに貢献するかもしれない人のための開発ガイドを含めることができます。
APIドキュメント: これはプロジェクトの詳細なドキュメントです。 ここには、ユーザー向けの関数、クラス、メソッド、属性、およびパッケージの使用に役立つ追加的な高レベルのディスカッションを含む、パッケージのAPIのドキュメントを保存します。
空間的なPythonライブラリであるGeoPandasのドキュメントのランディングページには、上記の4つの要素が指定されています。 ランディングページはシンプルで、Sphinxカードを使って各要素にユーザーを誘導していることに注目してください。#
NOTE: 多くの場合、 README ファイルと CONTRIBUTING ファイルをドキュメントに含めることができま、これらのファイルには、上に挙げた構成要素のいくつかが含まれているかもしれません。
Tip
Sphinxではincludeディレクティブを使ってファイルをインクルードすることができます。 下記は myst 構文を使った例です。
```{include} ../README.md
```