Python パッケージングガイドへの貢献#

ガイドはコミュニティの情報源です。

TL;DR#

issueやプルリクエストという形での貢献を歓迎します:

ガイドに含めるべきもののアイデアがあれば、ここにissueを開いてください。
もしタイプミスを見つけたら、遠慮なく submit a pull request して直接テキストを修正してください。あるいは、プルリクエストに抵抗がある場合は、遠慮なくissueを開いてください。
このガイドを他の言語に翻訳することに興味がある方は、翻訳ガイドをご覧ください。
ガイドブックの内容をもっと大きく変えてほしいという方は、まずissueを投稿してください！

どのように貢献すればいいのかわからない、あるいはgitやgithubに詳しくないという方は、このガイドを参考にしてください。

Python パッケージングガイドの構成#

Python パッケージングガイドは myST (MarkDown と rST の変種) で書かれており、 Sphinx という Python で構築されたドキュメントエンジンを使って、オンラインに表示される HTML バージョンをビルドしています。

ガイドの作成プロセスを管理するためにNoxというツールを使っています。

貢献するための2つのアプローチ#

このガイドには2つの方法で貢献することができます。

最初のアプローチは、あなたのコンピュータにあるガイドのローカルコピーを使用することです。このオプションは、より複雑なセットアップを必要としますが、プルリクエストを提出する前に、ガイドをローカルでビルドし、あなたの貢献がバグを引き起こしていないことを確認することができます。これは、新しいセクション全体を書くような、より大きな貢献のために推奨されるアプローチです。

二つ目の方法は、GitHub のウェブサイトで直接貢献する方法です。この方法ではコンピュータのセットアップは不要で、PRを投稿した時点であなたの貢献は (継続的インテグレーション) テストされますが、問題が発生した場合にフィードバックを得るまでに時間がかかります。誤字脱字の修正のような小さな貢献をする場合や、オープンソースへの貢献が初めてで、最初のアプローチが敷居が高いと感じる場合に最適な方法です。

リポジトリをフォークする#

Independently of the approach you choose, the first step is to fork the Python Packaging Guide repository into your personal GitHub space. You can do this by clicking the "Fork" button in the top right corner of the repository page.

Learn more: Fork and Clone GitHub Repos is a good resource to learn more about forking.

レポジトリをフォークする、

GitHubにログインしていることを確認してください。
フォークしたいリポジトリ、ここでは Pythonパッケージングガイドリポジトリに移動します。
ページの右上に 'Fork' ボタンがあります。そのボタンをクリックしてください。新しいページが表示され、そこで '新しいフォークを作成' します。デフォルトの入力のまま、'Create fork' をクリックします。これで、 https://github.com/<username>1/python-package-guide にリポジトリのコピーが作成されます。 <username> はあなたの GitHub ユーザー名です。

GitHubウェブサイトを通じて貢献する#

MarkDownファイルの編集方法#

The Python Packaging Guide is written in myST, a variant of MarkDown. You can edit the files directly in the GitHub website. To do so, navigate to the file you want to edit and click the pencil icon in the top right corner of the file.

Edit file in GitHub — An image showing how to edit a file in GitHub. The pencil icon is highlighted with a red rectangle.#

An image showing when a file is being edited in GitHub. The file content is displayed in a text editor.#

To preview your changes, click the "Preview changes" tab.

Preview changes in GitHub — An image showing how to preview changes in GitHub. The file content is displayed in a text editor. The preview changes tab is highlighted with a red rectangle.#

変更をコミットする方法#

When you are done editing the file, scroll down to the bottom of the page. You will see a section called "Commit changes". Here you can write a title and a description for your changes. Make sure to write a clear and concise title that describes the changes you made.

Commit changes in GitHub — An image showing how to commit changes in GitHub. The commit message is displayed in a text editor. The commit changes section is highlighted with a red rectangle.#

After writing your commit message, click the "Commit changes" button to save your changes.

あなたのコンピュータでローカルに貢献する#

フォークしたリポジトリをクローンする#

To clone your forked repository to your computer, you need to copy the URL of your forked repository and run the following command in your terminal:

git clone <URL>

Replace <URL> with the URL of your forked repository. You can find the URL by clicking the green "Code" button on your forked repository page.

Clone repository in GitHub — An image showing how to clone a repository in GitHub. The URL of the repository is displayed in a text editor. The code button is highlighted with a red rectangle.#

新しいブランチを作る#

Before making any changes, you should create a new branch to work on. This will help keep your changes separate from the main branch and make it easier to submit a pull request.

To create a new branch, run the following command in your terminal:

git checkout -b <branch-name>

仮想環境を作る#

To build the guide locally, you need to create a virtual environment and install the dependencies. You can do this by running the following commands in your terminal:

On Windows:

python -m venv .venv
.venv\Scripts\activate

On MacOS and Linux:

python -m venv .venv
source .venv/bin/activate

開発依存パッケージをインストールする#

To install the development dependencies, run the following command in your terminal:

python -m pip install -e .[dev]

変更をコミットする#

After making your changes, you need to commit them to your local repository. To do this, run the following commands in your terminal:

To see the changes you made:
```
git status
```
To add the changes to the staging area:
```
git add .
```

To commit the changes:

git commit -m "Your commit message here"

Replace "Your commit message here" with a clear and concise message that describes the changes you made.

ローカルでのガイドのビルド方法#

To build the guide locally, you can use the nox command. This will run the default nox session, which builds the guide and opens it in your browser.

To see the different sessions available, you can run the following command in your terminal:

nox --list-sessions

There are different sessions in nox related to building the docs: docs, docs-test, docs-live. You can run them by specifying the session name after the nox command.

docs: this session builds the guide and opens it in your browser.
```
nox -e docs
```
To see the guide built locally, open the file _build/html/index.html in your browser.
docs-test: this session runs the tests for the guide.
```
nox -e docs-test
```
If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request.
docs-live: this session builds the guide and opens it in your browser with live reloading.
```
nox -e docs-live
```
open the local version of the guide in your browser at localhost shown in the terminal.

プルリクエストを提出する前に#

Before submitting your pull request, make sure to run the tests and check the formatting of your code.

nox -e docs-test

If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request. Also make sure to check the formatting of your documentation by building the docs locally and checking that your changes look correct.

あなたの貢献のプルリクエストを投稿する#

プルリクエストの作り方#

To open a pull request on GitHub, navigate to the main page of your forked repository and click on the "Pull requests" tab.

Pull requests tab in GitHub — An image showing how to navigate to the pull requests tab in GitHub. The pull requests tab is highlighted with a red rectangle.#

Click on the "New pull request" button.

New pull request button in GitHub — An image showing how to create a new pull request in GitHub. The new pull request button is highlighted with a red rectangle.#

Write a clear and concise title and description for your pull request. Make sure to describe the changes you made and why they are necessary.

プルリクエストを提出するとどうなるか(CI/CD)#

Once you submit a pull request, a series of checks will be run to ensure that your changes do not introduce any bugs or errors. These checks include:

Code formatting and styles: checks that your code is formatted correctly, by pre-commit.ci - pr check.
docs build: checks that the documentation builds correctly, using circleci.

You will see the status of these checks in your pull request.

Pull request checks in GitHub — An image showing the status of the checks in a pull request in GitHub. The checks are displayed in a table with a status icon next to each check. The checks are highlighted with a red rectangle.#

If any of these checks fail, you will see an error message in your pull request. You need to fix the errors before your changes can be merged.

Pull request checks failed in GitHub — An image showing the status of the checks in a pull request in GitHub. The checks are displayed in a table with a status icon next to each check. The checks that failed and the details link are highlighted with a red rectangle.#

To get more information about the errors, you can click on the "Details" link next to the failed check.

レビュープロセスに期待すること#

Once you submit a pull request, a maintainer of the repository will review your changes and provide feedback. The review process may involve:

Comments: the reviewer may leave comments on your pull request to ask questions or provide feedback.
Suggestions: the reviewer may suggest changes to your code or documentation.
Approvals: once the reviewer is satisfied with your changes, they will approve the pull request.

You can make changes to your pull request by pushing new commits to the branch. The pull request will be updated automatically with your new changes.

Once your pull request is approved, it will be merged into the main branch and your changes will be included in the guide.

追加ヘルプ#

助けを求めるには#

TODO: このセクションには、初心者の投稿者がさらに助けを必要とする場合に備えて、より多くの助けを見つけるためのオプション (イシューの作成、フォーラムへの投稿など) を記述してください。

その他のリソース#

TODO: また、GitHubのドキュメントのような初心者向けのドキュメントへのリンクも含める必要があります。

付録#

コード例#

このガイドでは、可能な限り iteralinclude Sphinx ディレクティブを使用して、コードと散文を分けています。ドキュメントで使用するコードは examples/ フォルダにあります。

ドキュメントでコードを参照する#

使用したい例がドキュメントの他の場所にある場合、 literalinclude ディレクティブをそのままコピーすれば、例は同期されたままになります。

すでに example フォルダに新しいドキュメントに使えそうなコードがある場合は、新しい literalinclude を作成して、それをサイトに展開することができます。動作する literalinclude に必要なのはコードへの相対パスだけですが、ほとんどの場合 :language: と :lines: も指定する必要があります。前者はコード例をより美しくし、後者は将来的なコードの変更からサンプルを守ることができます。

プロからのヒント : :lines: の代わりに :start-after:, :start-at:, :end-before:, :end-at: オプションもあります。また、サンプルコードがPythonの場合、 :pyobject: を使用すると、コードのリファクタリングがあっても同じドキュメント内容を維持することができます。

If you need example code that doesn't yet exist in examples/ see creating code for documentation.

ドキュメント用コードの作成#

コードブロックが役立つ場所に出くわしたら、コードフェンス (``` ブロックテキスト)と一緒にインラインで書く代わりに、独自の形式でファイルとして書くことができます。あなたの例はすでに存在しているかもしれません; ドキュメントのコードを参照するを参照してください。

既存のサンプルファイルのどれにも当てはまらない新しいサンプルを追加したい場合は、新しいファイルを作成して literalinclude ブロックで参照することができます。もしそのファイルが既存のサンプルプロジェクトの中にあるのが理にかなっているのであれば、そこに追加してください。そうでなければ、 examples ディレクトリに新しいフォルダを作成してください。

既存の例が不完全であったり、新しい例を既存のファイルに追加することに意味がある場合は、先に進んで追加してください。可能な限り、例を書き直すのではなく、拡張してください。例えば、ファイルの最後に新しい関数を追加したり、クラス内の既存のメソッドの後に新しいメソッドを追加したりします。

例題のコードは正しさをチェックされるので、新しい例題を追加するには、カバレッジのためのテストを追加する必要があるかもしれないし、失敗したテストを修正する必要があるかもしれません。

⚠️ 警告: 既存のサンプル・コードを変更する場合、特にファイルの末尾に追加する以上の変更を加える場合は、細心の注意が必要です。すべてのコード例は（潜在的に）共有例です。これにより、ガイド内のサンプルはより一貫したものになりますが、ある特定のユースケースのためにサンプルを修正する場合、アクションが遠のく可能性があります。もし既存のサンプルを修正することに気づいたら、このコマンドを実行し、新しいビルドでそれらのページをチェックしてみてください。

grep -lr '\.\./examples/path/to/modified\.py' documentation/

例:

このようにマークダウンでサンプルコードを書くのではなく

Here is an example Python function:

```python
def is_empty(x):
    return not bool(len(x))
```

python は .py ファイルに展開することができます。

def is_empty(x):
    return not bool(len(x))

Here is an example Python function:

:::{literalinclude} ../examples/contributing_example.py
:language: python
:lines: 1-2

別の例として、 pyproject.toml の一部だけを表示する必要がある場合、我々はすでに完全なプロジェクト定義を持っているので、関連する部分を見つけるだけでよいです。

こう書く代わりに

Classifiers are just a list of plain strings
```toml
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: BSD License",
    "Operating System :: OS Independent",
]
```

例は、既存のtomlファイルから抽出することができます

:::{literalinclude} ../examples/pure-hatch/pyproject.toml
:language: toml
:start-at: classifiers = [
:end-at: ]