Sphinxへの貢献¶

バグ報告や機能要望の提出、新しいドキュメントの作成、新しい動作や修正された動作のパッチの提出など、Sphinxに貢献する方法はたくさんあります。このガイドは、その開始方法を説明するものです。

ヘルプ¶

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

Stack Overflow (タグ: python-sphinx): 使用法と開発に関する質疑応答。
GitHub Discussions Q&A: 議論のための質疑応答スタイルのフォーラム。
sphinx-users <sphinx-users@googlegroups.com>: ユーザーサポートのためのメーリングリスト。
sphinx-dev <sphinx-dev@googlegroups.com>: 開発関連の議論のためのメーリングリスト。
irc.libera.chat の #sphinx-doc: 開発に関する質問やユーザーサポートのためのIRCチャンネル。

バグ報告と機能要望¶

Sphinxで問題が発生した場合、または新機能のアイデアがある場合は、GitHubのissue trackerに提出してください。

バグ報告の場合は、ビルドプロセス中に生成された出力と、未処理の例外が発生した後にSphinxが作成するログファイルを含めてください。このファイルの場所は、エラーメッセージの最後に表示されるはずです。また、sphinx-build --bug-reportの出力も含めてください。

関係するソースファイルを含めるか、リンクを提供することで、問題の解決に役立つ場合があります。可能であれば、エラーを生成する最小限のプロジェクトを作成し、代わりにそれを投稿してください。

コードの貢献¶

SphinxのソースコードはGitを使用して管理され、GitHubでホストされています。新しい貢献者がSphinxにコードを提出する推奨方法は、このリポジトリをフォークし、変更をフォークにコミットした後、プルリクエストを提出することです。その後、プルリクエストはメインリポジトリにマージされる前に、コア開発者の1人によって承認される必要があります。

はじめに¶

パッチの作成を開始する前に、オープンなissueを確認するか、新しくissueを開いて、機能のアイデアやバグに関する議論を開始することをお勧めします。問題や変更について不安や不確実な場合は、議論を開始してください。

これらは、Sphinxの開発を開始するために必要な基本的な手順です。

GitHubでアカウントを作成します。
GitHubインターフェースを使用して、メインのSphinxリポジトリ(sphinx-doc/sphinx)をフォークします。
フォークされたリポジトリを自分のマシンにクローンします。
```
git clone https://github.com/<USERNAME>/sphinx
cd sphinx
```
仮想環境をセットアップします。

これは、toxのおかげで単体テストには必要ありませんが、sphinx-buildをローカルで実行したり、toxの助けを借りずに単体テストを実行したりする場合は必要です。
```
virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .
```
新しい作業ブランチを作成します。好きな名前を選択してください。
```
git switch -c feature-xyz
```
ハック、ハック、ハック。

バグが修正されたこと、または機能が期待どおりに動作することを示すテストとともにコードを記述します。
修正または機能が些細なものでない場合（小さなドキュメントの更新、タイプミスの修正）、CHANGES.rstに箇条書きを追加してからコミットします。
```
git commit -m '#42: Add useful new feature that does this.'
```
GitHubは、issue trackerを自動的に更新するために使用できる特定のフレーズを認識します。例えば
```
git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
```
issue #42を閉じます。
ブランチの変更をGitHub上のフォークされたリポジトリにプッシュします。
```
git push origin feature-xyz
```
ブランチからmasterブランチにプルリクエストを送信します。
コア開発者または貢献者が変更を確認するのを待ちます。

コーディングスタイル¶

Sphinxのコードを書くときは、次のガイドラインに従ってください。

プロジェクトの残りの部分で使用されているものと同じコードスタイルを使用するようにしてください。
些細な変更でない場合は、CHANGES.rstファイルを更新してください。変更によって既存の動作が変更される場合は、これを文書化してください。
新機能は文書化する必要があります。適切な場合は、例とユースケースを含めます。可能であれば、生成された出力に表示されるサンプルを含めます。
新しい設定変数を追加するときは、必ず文書化し、それが十分に重要な場合はsphinx/cmd/quickstart.pyを更新してください。
適切な単体テストを追加します。

スタイルとタイプのチェックは、次のように実行できます。

ruff check .
mypy

単体テスト¶

Sphinxは、Pythonコードにはpytest、JavaScriptにはJasmineを使用してテストされます。

Pythonの単体テストを実行するには、多くのターゲットを提供し、複数の異なるPython環境でのテストを可能にするtoxを使用することをお勧めします。

可能なすべてのターゲットを一覧表示するには
```
tox -av
```
Python 3.12など、特定のPythonバージョンの単体テストを実行するには
```
tox -e py312
```
pytestへの引数はtoxを介して渡すことができます。たとえば、特定のテストを実行するには
```
tox -e py312 tests/test_module.py::test_new_feature
```

ローカル環境に依存関係をインストールしてテストすることもできます。

pip install .[test]

JavaScriptテストを実行するには、npmを使用します。

npm install
npm run test

ヒント

jasmineは、テストブラウザとして使用するFirefoxバイナリが必要です。

Unixシステムでは、コマンドラインでcommand -v firefoxを実行して、firefoxバイナリの存在と場所を確認できます。

新しい単体テストは、必要に応じてtests/ディレクトリに含める必要があります。

バグ修正の場合は、最初に変更なしでは失敗し、適用後に成功するテストを追加します。
sphinx-buildの実行が必要なテストは、可能であれば既存のテストモジュールの1つに統合する必要があります。
テストは迅速で、関連するコンポーネントのみをテストする必要があります。テストスイートの実行時間が1分を超えないようにすることを目指しています。一般に、完全な統合テストが必要な場合を除き、appフィクスチャとapp.build()の使用は避けてください。

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

バージョン 1.5.2 で変更: Sphinxはnoseからpytestに切り替えられました。

ドキュメントの貢献¶

ドキュメントへの貢献には、doc/フォルダーにあるソースファイルを変更することが含まれます。開始するには、まずはじめにに従い、次に以下の手順に従ってドキュメントを操作する必要があります。

次のセクションでは、ドキュメントへの貢献を開始する方法と、使用するいくつかの異なるツールの主要な側面について説明します。

ドキュメントのビルド¶

ドキュメントをビルドするには、次のコマンドを実行します

sphinx-build -M html ./doc ./build/sphinx --fail-on-warning

これにより、Sphinxドキュメントのソースファイルが解析され、build/sphinx/htmlでプレビューするHTMLが生成されます。

ブラウザでプレビューできるドキュメントのライブバージョンをビルドすることもできます。変更を検出すると、編集を行うたびにページがリロードされます。それを行うには、次のコマンドを実行します

sphinx-autobuild ./doc ./build/sphinx/

翻訳¶

ビルドに含まれるSphinxのメッセージの一部は、いくつかのロケールに翻訳されます。翻訳は、マスターテンプレートsphinx/locale/sphinx.potから翻訳されたgettext .poファイルとして保持されます。

Sphinxは、Babelを使用してメッセージを抽出し、カタログファイルを管理します。utilsディレクトリには、ヘルパースクリプトbabel_runner.pyが含まれています。

python babel_runner.py extractを使用して、.potテンプレートを更新します。
python babel_runner.py updateを使用して、テンプレートファイルの現在のメッセージで、sphinx/locale/*/LC_MESSAGESにある既存のすべての言語カタログを更新します。
python babel_runner.py compile を使用して、.po ファイルをバイナリ .mo ファイルと .js ファイルにコンパイルします。

更新された .po ファイルが提出されたら、python babel_runner.py compile を実行して、ソースとコンパイル済みカタログの両方をコミットします。

新しいロケールが提出されたら、ISO 639-1 言語識別子を使用して新しいディレクトリを追加し、そこに sphinx.po を配置します。language の可能な値を doc/usage/configuration.rst で更新することを忘れないでください。

Sphinx のコアメッセージは、Transifex でも翻訳できます。Transifex から .po 形式で翻訳をプルするには、transifex_client Python パッケージによって提供される tx クライアントツールを使用できます。これを行うには、sphinx/locale に移動し、tx pull -f -l LANG を実行します。ここで、LANG は既存の言語識別子です。その後、python babel_runner.py update を実行して、.po ファイルが正規の Babel 形式になっていることを確認することをお勧めします。

デバッグのヒント¶

コードを変更した場合、ドキュメントをビルドする前に、make clean コマンドを実行するか、sphinx-build --fresh-env オプションを使用して、ビルドキャッシュを削除してください。
例外発生時に pdb を実行するには、sphinx-build --pdb オプションを使用します。
node.pformat() および node.asdom().toxml() を使用して、ドキュメント構造の印刷可能な表現を生成します。
設定変数 keep_warnings を True に設定すると、生成された出力に警告が表示されます。
設定変数 nitpicky を True に設定すると、Sphinx は既知のターゲットがない参照について警告します。
Docutils 設定ファイルでデバッグオプションを設定します。

生成されたファイルの更新¶

sphinx/search/non-minified-js/*.js 内の JavaScript ステミングアルゴリズムは、snowball を使用して生成されます。リポジトリをクローンし、make dist_libstemmer_js を実行してから、dist ディレクトリに生成された tarball を解凍します。

sphinx/search/minified-js/*.js 内の縮小化されたファイルは、uglifyjs（npm 経由でインストール）を使用して、縮小化されていないファイルから生成されます。-m オプションを付けて、マングリングを有効にします。
tests/js/fixtures/* ディレクトリにある searchindex.js ファイルは、tests/js/roots/* にある対応する入力プロジェクトで標準の Sphinx HTML ビルダーを使用して生成されます。フィクスチャは、Sphinx JavaScript 単体テストで使用されるテストデータを提供し、utils/generate_js_fixtures.py スクリプトを実行することで再生成できます。