イントロダクション

これはSphinxドキュメンテーションビルダーのドキュメントです。Sphinxは一連の reStructuredText (以下reST) のソースファイルを様々な出力形式に変換したり、クロスリファレンスやインデックスなどを自動生成するツールです。これは、もしreSTフォーマットのドキュメント群が含まれるディレクトリがあったとしたら、Sphinxはそこから非常によくまとまった配置のHTMLファイル群を生成することができるということを意味しています。サブディレクトリにソースが分かれていても問題はありません。また、結果のHTMLはブラウザで簡単に見たり、ナビゲーションもしっかりしたものになります。それだけではなく、同じソースファイルから、同様にLaTeXファイルも出力することができ、これをコンパイルすることでPDFバージョンのドキュメントも生成することができますし、 rst2pdf を使用すると、直接PDFファイルを生成することもできます。

このドキュメントでは、自動生成のAPIのドキュメントではなく、手で作成するドキュメンテーションにフォーカスします。そのようなドキュメントのサポートに関してはまだ限定的にはあります(手で作成するコンテンツも自由に追加できるようにする予定)が、もし純粋なAPIドキュメントが必要であれば、 Epydoc をご覧ください。こちらもreSTを解釈することができます。

ドキュメント執筆に関する一般的な「イントロダクション」、すなわち、「なにを」「どのように」書くのかについては、Eric Holscherが書いた Write the docs も参照してください。

他のシステムからの変換

このセクションでは、他のドキュメントシステムからreStructuredText/Sphinxへの移行を考えている人達へのヒントを集めています。

  • Gerard FlanaganはHTMLからreSTに変換するスクリプトを作成しました。スクリプトは Python Package Index にあります。

  • 古いPythonのドキュメントをSphinxにコンバートするには、専用のコンバート用のツールを PythonのSVNリポジトリ で見つけることができます。これを使えば、Python-docスタイルのLaTeXのマークアップをSphinx reSTに変換できます。

  • Marcin WojdyrはDocbookをreST+Sphinxマークアップに変換するスクリプトを作成しました。 Google Code にあります。

  • Christophe de VienneはOpen/LibreOfficeの文章をSphinxに変換するツール odt2sphinx を作成しました。

  • 異なるマークアップ言語感の変換には、Pandoc が非常に有用です。

他のシステムと併用

FAQの中の関連のリスト を参照してください。

前提条件

Sphinxが動作するためには、最低でも**Python 2.7** か **Python 3.4**が必要となります。docutils と Jinja2_の ライブラリーも同様に必要です。docutilsはバージョン 0.10か、何らかのSVNのトランクスナップショット(壊れていないもの)のもとでSphinx が動作するはずです。もしソースコードのハイライト表示を望むなら、Pygments_ライブラリーもインストールしなければなりません。

使用方法

導入の説明にあたっては、 Sphinxの最初の一歩 を参照してください。このドキュメントには、説明しているそれぞれの内容に対して、発展的な内容を説明しているセクションへのリンクが含まれています。