Sphinx開発者のためのガイド

概要

このドキュメントは Sphinx の開発プロセスについて記述します。 Sphinx は、開発者によって使用されるドキュメンテーションシステムなので、その開発者が作るシステムを他の開発者に使ってもらうためのドキュメントに使用されます。そのようなシステムを利用する開発者もまた Sphinx を使用してドキュメントを書くかもしれません。

SphinxのソースコードはGitで管理され、GitHubでホストされています。

git clone git://github.com/sphinx-doc/sphinx

コミュニティ

sphinx-users <sphinx-users@googlegroups.com>

ユーザーサポートのためのメーリングリスト

sphinx-dev <sphinx-dev@googlegroups.com>

開発関連の議論を行うためのメーリングリスト

#sphinx-doc on irc.freenode.net

開発の質問やユーザーサポートのためのIRCチャンネル

バグ報告と機能のリクエスト

If you have encountered a problem with Sphinx or have an idea for a new feature, please submit it to the issue tracker on GitHub or discuss it on the sphinx-dev mailing list.

For bug reports, please include the output produced during the build process and also the log file Sphinx creates after it encounters an unhandled exception. The location of this file should be shown towards the end of the error message.

関係するソースファイルを含めるか、リンクを提供することで、私たちが問題を解決する助けになります。可能なら、エラーを生成する最小のプロジェクトを作成して、代わりにそれを送信するようにしてください。

Sphinx への貢献

新しいコントリビュータが Sphinx にコードを提出する際に推奨される方法は、GitHub上のリポジトリをフォークして、変更をコミットした後で pull request を送ることです。その後 pull request は、メインリポジトリにマージされる前に、コア開発者のうちの1人によって承認される必要があります。

  1. 機能のアイデアやバグについての議論を行うために、進行中のissueチケットを探すか、または新しいチケットを作成してください。

  2. If you feel uncomfortable or uncertain about an issue or your changes, feel free to email the sphinx-dev mailing list.

  3. Fork the repository on GitHub to start making your changes to the master branch for next MAJOR version, or X.Y branch for next MINOR version (see Branch Model).

  4. バグが修正されたことや、機能が想定どおりに動作することを確認するテストを記述します。

  5. プルリクエストを送信し、それがマージされてリリースされるまで、bug the maintainerします。AUTHORS に自分を追加したり、 CHANGES に変更を書いたりしてください。

はじめに

これらは Sphinx の開発を始めるために必要な基本的なステップです。

  1. GitHub上にアカウントを作る。

  2. GitHubインタフェースを使用して、 Sphinx のメインリポジトリ (sphinx-doc/sphinx) をフォークする。

  3. フォークしたリポジトリをあなたのマシンにクローンする。

    git clone https://github.com/USERNAME/sphinx
    cd sphinx
    
  4. 適切なブランチをチェックアウトする。

    Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ).

    For changes that preserves backwards-compatibility of API and features, they should be included in the next MINOR release, use the X.Y branch.

    git checkout X.Y
    

    For incompatible or other substantial changes that should wait until the next MAJOR release, use the master branch.

    For urgent release, a new PATCH branch must be branched from the newest release tag (see Branch Model for detail).

  5. Setup a virtual environment.

    This is not necessary for unit testing, thanks to tox, but it is necessary if you wish to run sphinx-build locally or run unit tests without the help of tox.

    virtualenv ~/.venv
    . ~/.venv/bin/activate
    pip install -e .
    
  6. 新しい作業ブランチを作成します。ブランチ名は好きな名前を選んで構いません。:

    git checkout -b feature-xyz
    
  7. ハック・ハック・ハック

    コードで作業する際の tips については、 コーディングガイド を参照してください。

  8. テスト・テスト・テスト

    Testing is best done through tox, which provides a number of targets and allows testing against multiple different Python environments:

    • To list all possible targets:

      tox -av
      
    • To run unit tests for a specific Python version, such as 3.6:

      tox -e py36
      
    • To run unit tests for a specific Python version and turn on deprecation warnings on so they're shown in the test output:

      PYTHONWARNINGS=all tox -e py36
      
    • To run code style and type checks:

      tox -e mypy
      tox -e flake8
      
    • Arguments to pytest can be passed via tox, e.g. in order to run a particular test:

      tox -e py36 tests/test_module.py::test_new_feature
      
    • ドキュメントをビルドする:

      tox -e docs
      
    • To build the documentation in multiple formats:

      tox -e docs -- -b html,latexpdf
      
    • To run JavaScript tests with Karma, execute the following commands (requires Node.js):

      npm install
      npm run test
      

    You can also test by installing dependencies in your local environment.

    pip install .[test]
    

    New unit tests should be included in the tests directory where necessary:

    • バグフィックスについては、まず最初に問題を再現する、つまり失敗するテストを追加してください。その後テストが通るようにバグを修正します。

    • Tests that need a sphinx-build run should be integrated in one of the existing test modules if possible. New tests that to @with_app and then build_all for a few assertions are not good since the test suite should not take more than a minute to run.

  9. もし、修正が限定的なもの(ドキュメントの微細な修正、スペルミス)ではない場合は、 CHANGES に「黒丸 bullet point」を追加してからcommit::してください。

    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 をクローズします。

  10. 変更をGithubにあるフォークしたあなたのリポジトリのブランチに push する。

    git push origin feature-xyz
    
  11. Submit a pull request from your branch to the respective branch (master or X.Y).

  12. コア開発者が変更をレビューするのを待つ。

コア開発者

Sphinx のコア開発者は、メインリポジトリへの書き込みアクセスを持っています。コア開発者は、変更をコミットすることができ、 pull request を受理/却下することができ、課題トラッカー上のアイテムを管理することができます。

Sphinx の開発に参加するために、コア開発者である必要はなく、書き込みアクセスを持つ必要もありません。あなたはパッチを提出したり、フォークしたリポジトリから pull request を作成したりすることができます。そして、コア開発者があなたの代わりに変更を追加します。

以下はコア開発者のためのいくつかの一般的なガイドラインです:

  • 不確かな変更や広範囲に及ぶ変更は、メインリポジトリに直接コミットする代わりに pull request を提出すべきです。その pull request は、マージされる前に他のコア開発者によってレビューされるべきです。

  • 自明な変更は直接コミットできますが、リポジトリを良好に動作する状態に保ち、変更を push する前にすべてのテストが通ることを確かめるようにしてください。

  • 誰か他の人によって書かれたコードをコミットする場合、コミットメッセージといずれかの適切な CHANGES エントリーの中でオリジナルの作者に言及してください。

言語の更新

Sphinxが出力するメッセージの一部はいくつかの言語に翻訳されています。翻訳は gettext の .po ファイルに保存されており、マスターとなるテンプレートの sphinx/locale/sphinx.pot から翻訳されています。

Sphinxはメッセージを展開し、カタログファイルを管理するために Babel を使っています。これは setup.py に含まれています。

  • .pot テンプレートを更新するには python setup.py extract_messages を使います。

  • テンプレートファイルにある現時点でのメッセージで sphinx/locale/*/LC_MESSAGES のすべての既存のカタログを更新するには、 python setup.py update_catalog を使います。

  • .po ファイルをバイナリの .mo ファイルと .js ファイルにコンパイルするには python setup.py compile_catalog を使います。

更新された .po ファイルが投稿された場合、ソースとコンパイルされたカタログの両方をコミットするために compile_catalog を実行します。

When a new locale is submitted, add a new directory with the ISO 639-1 language identifier and put sphinx.po in there. Don't forget to update the possible values for language in doc/usage/configuration.rst.

Sphinxのメインとなるメッセージは Transifex でも翻訳されています。Pythonパッケージの "transifex_client" の中に tx と呼ばれるクライアントツールがあり、 これを使うとTransifexから翻訳を .po フォーマットで取得できます。そのためには、 sphinx/locale に行き、 tx pull -f -l LANG を実行します。なお、LANGは既存の言語の識別子です。 .po ファイルが正しいBabel形式かどうかを確認するために python setup.py update_catalog を実行すると良いでしょう。

コーディングガイド

  • プロジェクトの他の部分で使用されているのと同じコードスタイルをなるべく使用してください。詳細は、 Pocoo Styleguide を参照してください。

  • 自明でない変更については、 CHANGES ファイルを更新してください。あなたの変更が既存の振る舞いを変更する場合は、このことをドキュメント化してください。

  • 新機能はドキュメント化されなければなりません。適切な場合は例とユースケースを含めてください。可能なら、生成される出力に表示されるサンプルを含めてください。

  • When adding a new configuration variable, be sure to document it and update sphinx/cmd/quickstart.py if it's important enough.

  • 適切なユニットテストを追加してください。

デバッグ tips

  • コードに変更を加えた場合は、コマンド make clean の実行または sphinx-build -E オプションの使用によりドキュメントをビルドする前にビルドキャッシュを削除してください。

  • Use the sphinx-build -P option to run pdb on exceptions.

  • ドキュメント構造の表示可能な表現を生成するには node.pformat()node.asdom().toxml() を使用してください。

  • 生成される出力に警告が表示されるよう、設定変数 keep_warningsTrue を設定してください。

  • 既知のターゲットのない参照について Sphinx が警告するように、設定変数 nitpickyTrue を設定してください。

  • Docutils 設定ファイル 中でデバッグオプションを設定してください。

  • JavaScript ストリーミングアルゴリズムは modified snowballcode generator によって生成されます。 sphinx/search/*.py (en.py を除く)の中の 生成された JSX ファイルは このリポジトリ です。 生成された JavaScript は下記のコマンドを使用して取得することができます:

    npm install
    node_modules/.bin/grunt build # -> dest/*.global.js
    

Branch Model

Sphinx project uses following branches for developing that conforms to Semantic Versioning 2.0.0 (refs: https://semver.org/ ).

master

Development for MAJOR version. All changes including incompatible behaviors and public API updates are allowed.

X.Y

Where X.Y is the MAJOR.MINOR release. Used to maintain current MINOR release. All changes are allowed if the change preserves backwards-compatibility of API and features.

Only the most recent MAJOR.MINOR branch is currently retained. When a new MAJOR version is released, the old MAJOR.MINOR branch will be deleted and replaced by an equivalent tag.

X.Y.Z

Where X.Y.Z is the MAJOR.MINOR.PATCH release. Only backwards-compatible bug fixes are allowed. In Sphinx project, PATCH version is used for urgent bug fix.

MAJOR.MINOR.PATCH branch will be branched from the v prefixed release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent release is needed. When new PATCH version is released, the branch will be deleted and replaced by an equivalent tag (ex. v2.3.1).

非推奨の機能

次の2つの理由からSphinx内のコードは非推奨なものとなるかもしれません:

  • ある機能が後方互換のない方法で改良、修正された場合、古い機能,動作は非推奨となります。

  • Sphinxが現在サポートしているPythonのバージョンで収録されていないPythonライブラリを,Sphinxはバックポートとして収録することがあります。Pythonの旧バージョンで,当該ライブラリを収録していないものについてサポートをSphinxが打ち切るときに、そのライブラリはSphinxで非推奨となります。

As the 非推奨についての方針 describes, the first release of Sphinx that deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning (where XX is the Sphinx version where the feature will be removed) when the deprecated feature is invoked. Assuming we have good test coverage, these warnings are converted to errors when running the test suite with warnings enabled:

pytest -Wall

Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or silence any warnings generated when running the tests.

非推奨についての方針

MAJOR and MINOR releases may deprecate certain features from previous releases. If a feature is deprecated in a release A.x, it will continue to work in all A.x.x versions (for all versions of x). It will continue to work in all B.x.x versions but raise deprecation warnings. Deprecated features will be removed at the C.0.0. It means the deprecated feature will work during 2 MAJOR releases at least.

So, for example, if we decided to start the deprecation of a function in Sphinx 2.x:

  • Sphinx 2.x will contain a backwards-compatible replica of the function which will raise a RemovedInSphinx40Warning.

  • Sphinx 3.x will still contain the backwards-compatible replica.

  • Sphinx 4.0 will remove the feature outright.

デフォルトでは警告が表示されます。次のようにすることで、これらの警告表示を止めることができます:

  • PYTHONWARNINGS= make html (Linux/Mac)

  • export PYTHONWARNINGS= として、 make html を実行する(Linux/Mac)

  • set PYTHONWARNINGS= として ``make html``を実行する(Windows)

単体テスト

Sphinxのテストはpytestで行われてきました。Sphinx開発者はpytestの表記法を用いて単体テストを書きます。ユーティリティ関数とテストのためのpytest フィクスチャは``sphinx.testing``で提供されています。もしなたがSphinx拡張の開発者でしたら、pytestを使って単体テストを書くことができます。現時点では、テストの実装には``sphinx.testing``が有用でしょう。

How to use pytest fixtures that are provided by sphinx.testing? You can require 'sphinx.testing.fixtures' in your test modules or conftest.py files like this:

pytest_plugins = 'sphinx.testing.fixtures'

さらに詳しい使い方を知りたい場合は、tests/conftest.py と``tests`` ディレクトリ配下にある test_*.py ファイルらを参照してください。

注釈

Sphinx - 1.5.2以前は, Sphinx はnoseを使ってテストを走らせていました.

バージョン 1.6 で追加: sphinx.testing as a experimental.

バージョン 1.8 で追加: Sphinx also runs JavaScript tests.