Sphinx開発者のためのガイド

Abstract

このドキュメントは 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チャンネル

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

Sphinx に関する問題に遭遇したり、新機能に対するアイデアがある場合は、Github上の issue tracker に提出してください。あるいは sphinx-dev メーリングリスト上でそれについて議論してください。

バグレポートには、ビルドで生成された出力と、 Sphinx が未処理の例外に遭遇した後に生成するログファイルも含めてください。このファイルの場所は、エラーメッセージの終わりの方で示されているはずです。

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

Sphinx への貢献

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

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

  2. もし、あなたの課題や変更についてよく分からない問題があったり、しっくりしないのであれば、気軽に sphinx-dev@googlegroups.com にメールしてください。

  3. Github上の リポジトリ にあなたの変更を追加しましょう。 master ブランチは次のメジャーバージョン用で、 stable ブランチは次のマイナーバージョン用です。

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

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

Getting Started

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

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

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

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

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

    次のマイナーリリースに含まれるべき変更 (すなわちバグフィックス) については、 stable ブランチを使用してください。

    git checkout stable
    

    次のメジャーリリースまで待つべき新しい機能やその他の本質的な変更については、 master ブランチを使用してください。

  5. 任意: Python仮想環境をセットアップする:

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

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

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

  8. テスト・テスト・テスト。よくある手順:

    • ユニットテストを実行してください:

      pip install -r test-reqs.txt
      make test
      
    • Again, it’s useful to turn on deprecation warnings on so they’re shown in the test output:

      PYTHONWARNINGS=all make test
      
    • ドキュメントをビルドして、他のビルダーの出力をチェックしてください:

      cd doc
      make clean html latexpdf
      
    • tox を使って、異なる Python 環境の下でユニットテストを実行してください:

      pip install tox
      tox -v
      
    • 可能なら tests ディレクトリの中に新しいユニットテストを追加してください。

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

    • sphinx-build の実行が必要なテストは出来るだけ既存のテストモジュールへ統合してください。 @with_app に続いて build_all でわずかなアサーションを行なうのは良い案ではありません。 テストスイートの実行は 1 分以内で完了するべきだからです。

  9. もし、修正が限定的なもの(ドキュメントの微細な修正、スペルミス)ではない場合は、:file:`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. Githubインタフェースを使用して、あなたのブランチから sphinx-doc/sphinx の各ブランチ(masterstable)に pull request を送る。

  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 を実行します。

新しい言語が登録された場合、ISO 639-1の言語定義に従い新しいディレクトリを作成し、 sphinx.po をそこに置きます。 doc/config.rst にある language がサポートしている言語リストを更新することを忘れないように。

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 ファイルを更新してください。あなたの変更が既存の振る舞いを変更する場合は、このことをドキュメント化してください。

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

  • 新しい設定変数を加える場合、ドキュメント化が必要な内容であれば、 sphinx/quickstart.py を更新してください。

  • 一般的なフォーマットの問題 (末尾の空白、長い行など) をチェックするため、同梱されている utils/check_sources.py スクリプトを使用してください。

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

デバッグ tips

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

  • 例外が起きた時に Pdb を実行するには sphinx-build -P オプションを使用してください。

  • ドキュメント構造の表示可能な表現を生成するには 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
    

Deprecating a feature

There are a couple reasons that code in Sphinx might be deprecated:

  • If a feature has been improved or modified in a backwards-incompatible way, the old feature or behavior will be deprecated.
  • Sometimes Sphinx will include a backport of a Python library that’s not included in a version of Python that Sphinx currently supports. When Sphinx no longer needs to support the older version of Python that doesn’t include the library, the library will be deprecated in Sphinx.

As the Deprecation policy 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: python -Wall tests/run.py. Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or silence any warnings generated when running the tests.

Deprecation policy

A feature release may deprecate certain features from previous releases. If a feature is deprecated in feature release 1.A, it will continue to work in all 1.A.x versions (for all versions of x) but raise warnings. Deprecated features will be removed in the first 1.B release, or 1.B.1 for features deprecated in the last 1.A.x feature release to ensure deprecations are done over at least 2 feature releases.

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

  • Sphinx 1.4.x will contain a backwards-compatible replica of the function which will raise a RemovedInSphinx16Warning.
  • Sphinx 1.5 (the version that follows 1.4) will still contain the backwards-compatible replica.
  • Sphinx 1.6 will remove the feature outright.

The warnings are displayed by default. You can turn off display of these warnings with:

  • PYTHONWARNINGS= make html (Linux/Mac)
  • export PYTHONWARNINGS= and do make html (Linux/Mac)
  • set PYTHONWARNINGS= and do make html (Windows)