ライオンの顔像への貢献¶

エラー報告または特性要求を提出するか、新しい文書を作成するか、新しいまたは修復された行為にパッチを提出するかにかかわらず、様々な方法でSphinxに貢献することができます。本ガイドラインは、それの使用開始方法を説明するために使用されます。

助けを求める¶

Sphinxコミュニティは多くのメーリングリストとIRCチャネルを維持している.

マーク付きスタックオーバーフロー python-sphinx: 使用と開発に関する質疑応答。
ライオンの顔像-ユーザー<スフィンクス-ユーザー@googlegroups.com>: ユーザ支援のためのメーリングリスト.
Sphinx-dev<sphinx-dev@googlegroups.com>: 議論に関するメーリングリストを開発する.
Irc.freende.netの#sphinx-doc: IRC開発問題とユーザ支援チャネル.

エラー報告と機能要求¶

Sphinxを使用する際に問題や新しい機能の考えがあれば、それを提出してください issue tracker GitHubで議論したり sphinx-dev 名簿を郵送する。

エラー報告には、構築中に生成された出力と、Sphinxが未処理例外に遭遇した後に作成されたログファイルを含めてください。このファイルの位置はエラーメッセージの末尾に表示されるべきである.

関連するソースファイルを含むか、または提供するリンクは、この問題を解決するのに役立つかもしれません。可能であれば、エラーを発生させる最小項目を作成し、そのエラーを発行しようと試みます。

コードを書く¶

SphinxソースコードはGitを使用して管理され、ホストされています `GitHub`_ _。新しい貢献者がSphinxにコードを提出する方法を提案するのは、このリポジトリを派生し、派生した変更を提出した後にプル要求を提出することである。そして，引取要求を主バンクに統合する前に，コア開発者の1つの承認を得る必要がある.

スタート¶

パッチを開始する前に，未解決の問題があるかどうかをチェックしたり，ある機能的な考え方や誤りの議論を開始したりする新しい問題を開くことを提案する.何か問題や変更に気分が悪くなったり、確定しなかったりする場合は、いつでもおっしゃってください。 sphinx-dev 名簿を郵送する。

これらはSphinx上で開発を開始するための基本手順である.

GitHubにアカウントを作成します。
派生マスタSphinxリポジトリ (sphinx-doc/sphinx )GitHubインタフェースを使用します。
派生したリポジトリをあなたのコンピュータにクローンします。**
```
git clone https://github.com/USERNAME/sphinx
cd sphinx
```
お会計は適当な支店をお選びください。

Sphinxは意味バージョン制御2.0.0(https：//semver.org/)を用いている.

保留APIと機能の後方互換性の変更については、次のサブバージョンに含まれるべきですので、ご利用ください A.x ブランチ。**
```
git checkout A.x
```
次の主要バージョンまで待たなければならない不適合やその他の重大な変更については、ご利用ください master ブランチ。

緊急バージョンの場合は、最新バージョンから新しいパッチ分岐をマークしなければなりません(参照スフィンクスの再生過程詳細を見る)。
仮想環境を設定する。

これはユニットテストには必要ありませんこれは tox でも走りたいなら必要です sphinx-build ローカル実行ユニットテストまたは実行ユニットテストを支援します。 tox **
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
新しい仕事の枝を作成する。好きな名前を選んでください。**
```
git checkout -b feature-xyz
```
黒、黒、黒。

コードを作成すると同時にテストを行い，誤りが修復されたことや機能が期待どおりに動作していることを証明する.
…のために項目記号を追加する CHANGES 修復または機能が些細なものでない場合(小文書更新、スペルミス修復)、提出：
```
git commit -m '#42: Add useful new feature that does this.'
```
GitHubは、問題トラッカを自動更新するために使用可能ないくつかのフレーズを識別することができる。例えば：
```
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
```
42番の質問は終わります。
ノードの変更をGitHub上の分岐リポジトリにプッシュ：
```
git push origin feature-xyz
```
あなたの支店から対応する支店にプル式要求を提出します。 (master あるいは…。 A.x ）。
コア開発者があなたの変更をチェックするのを待っています。

コーディングスタイル.¶

Sphinxのためのコードを作成する際には、以下の基準に従ってください。

項目の残りと同じコードパターンの使用を試みる.
重要な変更については、更新してください CHANGES ファイルです。もしあなたの変更が既存の行動を変更した場合、これを記録してください。
新しい機能は記録されなければならない.適切な場合には例および用例が含まれる可能であれば、生成された出力に表示されたサンプルを含めてください。
新しい構成変数を追加する際は、必ず記録して更新してください sphinx/cmd/quickstart.py もしこのことが十分に重要なら。
適切なセルテストを追加します。

以下のコマンドを使用してスタイルやタイプチェックを実行することができます tox **

tox -e mypy
tox -e flake8

ユニットテスト¶

Sphinxは以下のツールを用いてテストを行った. `pytest`_ _Pythonコードと `Karma`_ _はJavaScriptを表す.

Pythonユニットテストを実行するためには、使用をお勧めします tox これは、多くの目標を提供し、複数の異なるPython環境のテストを可能にします：

可能なすべての目標を列挙するには、以下の操作を実行してください。
```
tox -av
```
Python 3.6のような特定のPythonバージョンのユニットテストを実行するには、以下の操作を実行してください。
```
tox -e py36
```
特定のPythonバージョンのユニットテストを実行し、廃棄警告を開き、テスト出力にこれらの警告を表示するために、以下の操作を実行してください。
```
PYTHONWARNINGS=all tox -e py36
```
以下の内容の論証 pytest 通過することができる tox 例えば、特定のテストを実行するために：
```
tox -e py36 tests/test_module.py::test_new_feature
```

また、ローカル環境に依存項目をインストールすることでテストを行うことができます。

pip install .[test]

JavaScriptテストを行いますので、ご利用ください npm **

npm install
npm run test

新しいユニットテストは tests 必要なときのディレクトリ：

エラー修復については、まず、変更なしに失敗し、変更を適用した後に通過するテストを追加します。
テストが必要なテスト sphinx-build 可能であれば、Runは既存のテストモジュールに統合されなければならない。新しいテストは @with_app そして build_all いくつかの断言が悪いからです テストキットの実行時間は1分を超えてはいけません それがそうです。

バージョン 1.8 で追加: SphinxはJavaScriptテストも実行しています

バージョン 1.6 で追加: sphinx.testing 実験として追加した.

バージョン 1.5.2 で変更: ライオンの顔像が鼻から一番辛いものに変わりました。

課題

以下は開発者ガイドである

試験のための実用的な関数及び最熱治具を提供する sphinx.testing それがそうです。Sphinx拡張の開発者であれば、pytestを使用してユニットテストを書くことができます。この時には sphinx.testing あなたのテストの実現に役立ちます。

提供された最高の装置をどのように使用するか sphinx.testing そうなの？あなたは要求することができます 'sphinx.testing.fixtures' あなたのテストモジュールでまたは conftest.py 以下に示すファイル：

pytest_plugins = 'sphinx.testing.fixtures'

もっと詳しい使い方を知りたい場合は、ご参照ください tests/conftest.py 他にも test_*.py 下の書類 tests カタログです。

文書を作成する¶

課題

より広範な文書投稿ガイドを追加する.

以下のツールを使用してドキュメントを構築することができます tox **

tox -e docs

訳文¶

Sphinxでは構築に入ったメッセージ部分がいくつかの地域に変換される.翻訳はgettext形式で保存する .po メインテンプレートから翻訳されたファイル sphinx/locale/sphinx.pot それがそうです。

ライオンの顔像を使っています Babel メールを抽出してディレクトリファイルを維持します。それは統合されています setup.py ：

使用 python setup.py extract_messages 更新するには .pot テンプレート
使用 python setup.py update_catalog 更新中の既存言語リストをすべて更新するには、以下の操作を実行してください sphinx/locale/*/LC_MESSAGES テンプレート·ファイル内の現在のメッセージ。
使用 python setup.py compile_catalog コンパイルするには .po ファイルをバイナリファイルに変換する .mo 書類と .js ファイルです。

更新されたときの .po ファイル提出後、COMPLE_CATALOGを実行してソースディレクトリとコンパイル後のディレクトリを提出します。

新しいエリア設定を提出する際には、ISO 639-1言語識別子を有する新しいディレクトリを追加し、 sphinx.po あそこにあります。以下の項目の可能値を更新することを忘れないでください language はい。 doc/usage/configuration.rst それがそうです。

Sphinxコアメッセージも Transifex それがそうです。あそこ tx クライアントツール、このツールは transifex_client Pythonバッグ、ここで使うことができます .po Transifexからフォーマットを設定する.この操作を実行するには、転送してください sphinx/locale そして走って tx pull -f -l LANG どこだ？ LANG 既存の言語識別子です。走るのはいいやり方です python setup.py update_catalog そしてそれを確実にするために .po ファイルは規範的なバーベルタワー形式を持っている。

ヒントをデバッグする¶

以下の命令を実行することでコードに変更が行われた場合は、文書を生成する前に生成キャッシュを削除してください make clean または使用する sphinx-build -E 選択します。
使用 sphinx-build -P 実行するオプション pdb 例外的な場合。
使用 node.pformat() そして node.asdom().toxml() 文書構造の印刷可能表現を生成する。
構成変数の設定 keep_warnings 至る True したがって，警告は生成された出力に表示される.
構成変数の設定 nitpicky 至る True このようにライオンの顔は既知の目標の引用がないと文句を言うだろう。
デバッグオプションを設定します。 Docutils configuration file それがそうです。
中のJavaScript語幹処理アルゴリズム sphinx/search/*.py (除く) en.py )から生成される modified snowballcode generator それがそうです。生成 JSX 書類のある this repository それがそうです。生成されたJavaScriptファイルは、以下のコマンドを使用して取得できます。
```
npm install
node_modules/.bin/grunt build # -> dest/*.global.js
```

Table of Contents

前のトピックへ

次のトピックへ