オープンソースPythonパッケージのドキュメント#
重要
ここで取り上げているツールは、コミュニティで一般的に使用されているものです。 ツールの進化に伴い、このガイドを更新します。 pyOpenSci査読のためにパッケージを提出し、パッケージを構築するためにガイドに記載されていない他のツールを使用する場合でも、査読のために提出することができます！ ここに挙げたツールは提案であり、要件ではありません。 私たちの要求は、あなたのパッケージの文書内容に焦点を当てています。
Pythonパッケージの成功にはドキュメンテーションが欠かせません#
ドキュメンテーションは、あなたのPythonオープンソースパッケージの成功にとって、コードそのものと同じくらい重要です。
もちろん、パッケージがどのようにタスクを遂行するかという点で、質の高いコードは価値があります。 しかし、もしユーザーがワークフローであなたのパッケージの使い方を理解していなければ、使ってもらえないでしょう。
さらに、どのように貢献するかを明確に文書化することは、あなたのパッケージへの貢献者の基盤を築きたいのであれば重要です。
Pythonパッケージユーザーの2つのタイプ#
パッケージのために書くドキュメントは、2つのタイプのユーザーをターゲットにすべきです:
1. Basic Tool Users#
基本ツールユーザーは、あなたのパッケージコードを Python ワークフローで使用する人たちです。 彼らはPythonやデータサイエンスの(より)初心者かもしれません。 あるいは熟練プログラマーかもしれません。 しかし、彼らはソフトウェア開発のバックグラウンドを持っていないかもしれません。 このようなユーザーは以下のことを知っておく必要があります:
パッケージのインストール方法
パッケージが必要とする依存関係をインストールする方法
コードベースの使い始め方
研究用アプリケーションでコードを使用する場合、あなたのコードをどのように引用し、クレジットを付与するかについての情報。
あなたのコードが使用するライセンスに関する情報を提供することで、運用環境においてコードをどのように使用できるか、または使用できないかを知ってもらいます。
2. Potential tool contributors#
もう一組のユーザは、経験が豊富で、かつ/またはあなたのパッケージにより深く関わっています。 彼らは潜在的な貢献者です。 これらのユーザーは:
ソフトウェア開発のバックグラウンドを持っているかもしれない、
また、パッケージのバグフィックスやドキュメントの更新に貢献できるかもしれません。
また、ドキュメントのスペルミスやチュートリアルのバグを見つけるユーザーもいるかもしれません。
これらのユーザーは、基本的なユーザーが必要とするすべてのものを必要としています。 しかし、彼らがあなたのパッケージにどのように貢献してほしいかを理解する必要もあります。 このような貢献者候補には、次のようなものが必要です:
パッケージリポジトリで使われているインフラを理解するための開発ガイドです。
どのような貢献の投稿を歓迎し、どのように貢献をしてほしいかを明確にした貢献ガイドライン。
重要
重要なのは、貢献の定義は幅広いということを覚えておくことです。貢献とは、バグ報告のような単純なものでもよいのです。あるいは、ドキュメントのスペルの問題を修正する。あるいは、彼らが発見したエッジケースをカバーする新しいテストを含むコード修正かもしれません。
pyOpenSciがPythonパッケージをレビューする際に注目するドキュメント要素#
pyOpenSciオープンピアレビューでは、あなたのツールのユーザーと潜在的な貢献者の両方をサポートする文書構造を探します。私たちが特にチェックするファイルや要素は、査読チェックリスト（下記リンク参照）に記載されています。
このガイドでは、各必須要素について説明し、パッケージの文書で考慮すべきその他の要素についても詳しく説明します。
pyOpenSci査読チェックリストを見る
MovingPandasのGitHubリポジトリから、CONTRIBUTING.md、README.md、CODE_OF_CONDUCT.md、LICENSE.txtを含む主要なファイルを抜粋。 ( スクリーンショットは2022年11月23日撮影 ) 。#
このPythonパッケージのドキュメントセクションの次は何でしょうか？#
pyOpenSciパッケージガイドのこのセクションでは、Pythonパッケージのドキュメントを設定するためのベストプラクティスを説明します。 また、ユーザー向けのドキュメントサイトを構築するために使用できるツールも提案します。