このガイドに貢献するには#

Python Packaging User Guide は貢献者を歓迎します！さまざまな貢献方法があります。例えば：

  • このガイドを読んでフィードバックを伝えること

  • 新しい貢献文書を査読すること

  • 既存の文書を修正すること

  • 新しく文書を書くこと

  • このガイドを翻訳する

Python Packaging User Guide のほとんどの作業は プロジェクトのGitHubリポジトリ で行われます。手始めに 未解決の問題 のリストをチェックアウトして(改善策の) プルリクエスト を送ってください。もしあなたがこのガイドに何かを書き加えたり編集したりするつもりなら、:ref:`スタイルガイド <contributing_style_guide>`__を読みましょう。

|PyPUG|に貢献を行うのであれば、あなたがPSFの`行動規範 <Code of Conduct>`__に従うことが期待されています。

文書の類型#

本プロジェクトは、特定の目的に合わせた四つの別個の文書類型で成り立っています。本プロジェクトでは、文書化の品質向上のために ディアタクシスプロセス に従うことを強く希望します。新たに追加することを提案する場合には、いずれかの適切な文書類型を選択してください。

チュートリアル型文書#

チュートリアルは目標を達成することで読者に新しい概念を教えることに注力しています。こうするべきだという意見に従ったステップバイステップのガイドになっています。大筋に無関係な警告や情報は省略されています。チュートリアル型文書の例.

ガイド型文書#

ガイドは特定のタスクを達成することに力点を置いていて、前提となる知識のレベルをある程度仮定することができます。ガイドはチュートリアルと似ていますが、しかしガイドはもっと狭い分野に明確に焦点を当てるものであり、必要に応じて多数の注意書きを行ったり追加的な情報を盛り込んだりすることができます。ガイドでは、そのタスクを達成するための複数のやり方を議論することもできます。ガイド型文書の例.

議論型文書#

議論型文書では、理解促進と情報提供に重点を置きます。議論型文書では、特定のゴールを念頭に置くことなく、ある特定の話題について深く探求します。議論型文書の例.

仕様型文書#

仕様型文書は、パッケージングツール間で相互運用のためのインターフェイスとして合意された事項について網羅的に文書化することに重点を置く参照用の文書です。仕様型文書の例.

翻訳#

我々は本プロジェクトの翻訳を管理するために Weblate を使用しています。 翻訳で貢献するには、Weblate上の`packaging.python.org`_ プロジェクトをご覧ください。

翻訳作業中になにか問題を感じたら、GitHub で issue を新規登録してください。

Tip

本プロジェクトの翻訳はすべて、 reStructuredText 文法 <reStructuredText syntax に従わなければなりません。

言語を追加する#

もしあなたの使う言語が packaging.python.org のリストに掲載されていなければ、言語一覧の下にある 新しい翻訳を始める <Start new translation> ボタンをクリックして、あなたが翻訳したい言語を追加してください。

reStructuredText文法に従う#

もしあなたがreStructuredText(RST)の書き方に慣れていないのであれば、Weblateで翻訳作業をする前に このガイド を読んでください。

参照リンクのテキストをそのまま翻訳することはやめてください

参照リンクのテキストを翻訳する時、単純に翻訳文で置き換えることはやめて下さい。

誤: 次のテキストを単純に翻訳する:
`some ref`_ -> `TRANSLATED TEXT HERE`_
正: 次のテキストをあなた自身の言語に翻訳して、さらに元の参照リンクを残す:
`some ref`_ -> `TRANSLATED TEXT HERE <some ref>`_

この文書を手元でビルドするには#

貢献寄与をするために必須というわけではありませんが、この文書を手元でビルドすることはあなたが行った変更をテストするのに役に立ちます。この文書を手元でビルドするには：

  1. Nox 。 pip を用いてnoxをインストールまたはアップグレードできます:

    python -m pip install --user nox

  2. Python 3.11。我々のビルドスクリプトは、通常、Python 3.11でのみ試験されている。あなたの使っているOSにPython 3.11をインストールする方法については、 Python のインストール指南のためのヒッチハッカーズガイド を見てほしい。

この文書をビルドするには、以下のシェルコマンドをプロジェクトのルートディレクトリで実行してください:

nox -s build

処理が終わると、``./build/html``の下にHTMLの出力ファイルが見つかるはずです。ここの``index.html``をブラウザで開くことでこの文書を閲覧することができますが、HTTPサーバを使って文書を提供する方がお勧めです。

HTTPサーバを用いてこの文書を提供するには、以下のコマンドを使います。:

nox -s preview

この文書は、 http://localhost:8000 から閲覧できます。

この文書が展開される場所#

この文書は ReadTheDocs を通じて展開されていて、 https://readthedocs.org/projects/python-packaging-user-guide/ から読めるようになっています。また、 Fast.ly から独自のドメイン名から提供されるようになっています(第二文はここだけでは意味が取れない)。

スタイルガイド#

このスタイルガイドは、あなたがどのように|PyPUG|を書くべきかについて推奨事項を与えます。あなたが書き始める前に目を通してください。スタイルガイドに従うことであなたの貢献がまとまりのある全体の中の一部として追加され、あなたの貢献がプロジェクトによって受け入れられやすくなります。

目的#

|PyPUG|の目的は、現在のツール群を用いてPythonプロジェクトをパッケージし、公開し、インストールする方法に関して権威ある参照先となることです。

スコープ#

この文書は、正確で的を射た推奨事項を添えた形で疑問に答え問題を解決することを意図しています。

この文書は網羅的であることを目指してはおらず、それぞれのプロジェクトのドキュメントを置き換えることも意図していません。例えば、pipにはたくさんのコマンドやオプションや設定事項があります。pipのドキュメントはその一つ一つについて詳細に記述していますが、この文書ではこの文書に記述されたタスクを完了するために必要となる部分に限ってpipに触れています。

想定される読者#

この文書の読者として想定されるのは、Pythonのパッケージを扱う方です。

Pythonコミュニティが巨大で温かいコミュニティであることを忘れないでください。読者は年齢・性別・教育程度・文化やその他諸々の点であなたと同じではないかもしれませんが、しかし、あなたがあなたにできる限りパッケージングについて学ぶことを称賛します。

とりわけ、Pythonを使う人なら誰でも自分をプログラマーだと思っているというわけではないことを覚えておいてください。この文書の想定される読者には、ソフトウェア開発を職業としているプロだけでなく、宇宙飛行士や画家あるいは学生も含まれるのです。

口調や語調#

この文書を書く時には、たとえあなたが答えを全部わかっていたとしても親しみやすく控えめな語調で書くように努力してください。

頭が良くてスキルのある人たちと一緒にPythonのプロジェクトをやるところを思い描いてください。あなたは彼らと働くのが好きだし、彼らもあなたと働くのが好きなのです。そんな人があなたに質問をして、あなたが答えを知っていたとしましょう。あなたはどんな風に応対しますか？*それ*こそが、あなたがこの文書を書く時のやり方なのです。

簡単な確認方法：あなたが書いたものを声に出して読めば、その口調や語調の感じがわかります。それはあなたが言いたかった感じに響きましたか、それとも、演説の一部みたいに聞こえましたか？短縮形を使っても構いませんし、曖昧な文法規則に固執することはありません。あなたはここに、もしそうしたいのならば前置詞で文を終わっても構わないと言う権限を与えられました。

ガイド文書を書くときは、論題の深刻さや難しさに合った語調に調整してください。もしあなたが入門篇のようなチュートリアルを書くときには冗談を挟んでも構いませんが、繊細な注意を必要とするセキュリティ上の推奨事項をカバーするなら冗談を全く入れないようにしたいと思うかもしれません。

慣例と手順#

読者に向けて書く

推奨事項や実行すべきステップを与えるときは、読者に*あなた*と呼びかけるか、または、命令法を用いて欲しい。

誤：それをインストールするために、ユーザは...を実行します。
正：...を実行することであなたはそれをインストールすることができます。
正：それをインストールするには、...を実行してください。
前提条件の明示

暗黙のうちに前提条件を仮定することのないようにしましょう。Webページとして提供するということは、この文書のどのページであってもそれが読者にとっての初めてのページになるかもしれないということです。

豊富な相互参照

あるツールや行為にあなたが初めて言及するときには、ガイドのそれを説明している部分へのリンク、または、どこか他の場所であっても適切な説明文書へのリンクも提供してください。

命名慣習を尊重すること

ツールやサイト、登場人物や他の適切な名詞に名前を付けるときには、大文字小文字などそれぞれが好んで使っている書き方を尊重してください。

誤：Pipは…
正：pipは…

誤：...はgithubにホストされている。
正：...はGitHubにホストされている。
ジェンダー中立なスタイルを使う

あなたが読者に直接呼びかけるときは「あなた」「あなたの」「あなたのもの」を使ってください。そうできない場合は代名詞として「彼ら」「彼らの」「彼らのもの」を使う(訳註：従来なら"he", "she"を用いた場所に"they"を使うことでジェンダーへの配慮を示す場合がある)か、または、代名詞をまったく使わないようにしましょう。

誤：メンテナンス担当者がファイルをアップロードする。それから、彼は…
正：メンテナンス担当者がファイルをアップロードする。それから、彼らは…
正：メンテナンス担当者がファイルをアップロードする。それから、メンテナンス担当者は…
見出しの付け方

見出しには読者が検索で使うような単語を使いましょう。質問の意図に答える形で見出しを書くのは良い方法です。読者が例えば MyLibraryをインストールするにはどうすれば良いの？ ということを知りたいとすれば、適切な見出しとしては MyLibraryをインストールするには のようになるでしょう。

見出し部分では通常の文章のように大文字小文字を使いましょう。言い換えるなら、ごく普通の文を書く時のように見出しを書きましょう。

誤：Pythonについてあなたが知っておくべき事柄 (訳註：日本語には大文字小文字の区別がないので誤例にならないのではないか)
正：Pythonについてあなたが知っておくべき事柄
数値の書き方

地の文では一から九までの数字を単語で書きましょう(訳註：日本語では漢数字にするよりもアラビア数字の方が適切かもしれません)。表の中ではアラビア数字で書きましょう。