イントロダクション

これはSphinxドキュメンテーションビルダーのドキュメントです。Sphinxは一連の reStructuredText (以下reST)のソースファイルを様々な出力形式に変換したり、クロスリファレンスやインデックスなどを自動生成するツールです。つまり、reSTフォーマットのドキュメント群を含むディレクトリを用意すれば、Sphinxはブラウザでの閲覧が容易でナビゲーションがある構造がしっかりしたHTMLファイル群を生成することができます。ソースがサブディレクトリに分かれていても問題はありません。それだけではなく、同じソースファイルから、LaTeXを用いてPDFファイルも生成することができます。

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

ドキュメント執筆一般に関する素晴らしい”入門書”―その理由と方法―としてEric Holscherが書いた Write the docs `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マークアップに変換するスクリプトを作成しました。 GitHub にあります。

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

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

他のシステムと併用

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

前提条件

Sphinx needs at least Python 3.5 to run. It also depends on 3rd party libraries such as docutils and jinja2, but they are automatically installed when sphinx is installed.

使用方法

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