イントロダクション

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

The focus is on hand-written documentation, rather than auto-generated API docs. Though there is support for that kind of documentation as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at Epydoc, which also understands reST.

For a great "introduction" to writing docs in general -- the whys and hows, see also Write the docs, written by Eric Holscher.

他のシステムからの変換

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

  • Gerard FlanaganはHTMLからreSTに変換するスクリプトを作成してきました。スクリプトは `Python Package Index <https://pypi.org/project/html2rest/>`_にあります。

  • For converting the old Python docs to Sphinx, a converter was written which can be found at the Python SVN repository. It contains generic code to convert Python-doc-style LaTeX markup to Sphinx reST.

  • Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx markup; it is at GitHub.

  • Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents to Sphinx: odt2sphinx.

  • To convert different markups, Pandoc is a very helpful tool.

他のシステムと併用

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

前提条件

Sphinx needs at least Python 3.5 to run, as well as the docutils and Jinja2 libraries. Sphinx should work with docutils version 0.12 or some (not broken) SVN trunk snapshot.

使用方法

See はじめに for an introduction. It also contains links to more advanced sections in this manual for the topics it discusses.