python-sphinx チュートリアル
python-sphinxを使い始める
サーチ…
備考
このセクションでは、python-sphinxの概要と、なぜ開発者がそれを使いたいのかを概説します。
また、Python-Sphinx内の大きなテーマについても言及し、関連するトピックにリンクする必要があります。 python-sphinxのドキュメントは新しいものなので、それらの関連トピックの初期バージョンを作成する必要があるかもしれません。
インストールまたはセットアップ
SphinxはPython Package Indexで利用できるので、 pipを使ってインストールすることができます：
pip install Sphinx
またはeasy_installを使用してインストールすることもできます
easy_install -U sphinx
次に、次のコマンドを実行して、正しくインストールされたことを確認できます。
> sphinx-quickstart --version
Sphinx v1.4.1
先に進む前に、Python PEP 8の特定のコードスタイルに従う必要があります。あなたが続いている場合はPEP 8ガイドラインをあなたがすることができ、文書の構造を定義スフィンクスにして起動し、あなたのドキュメントを構築します 。
クイックスタート
開始するには、プロジェクトディレクトリのルートに移動して実行します。
$ sphinx-quickstart
プロジェクトのドキュメントを作成するためのオプションが表示されます。デフォルト設定では、以下のコマンドを実行します。
Prompt Choice
> Root path for the documentation [.]: <ENTER>
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]: <ENTER>
> Project name: an_example_pypi_project
> Author name(s): Andrew Carter
> Project version: 0.0.1
> Project release [0.0.1]: <ENTER>
> Source file suffix [.rst]: <ENTER>
> Name of your master document (without suffix) [index]: <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]: n
> coverage: checks for documentation coverage (y/N) [n]: n
> pngmath: include math, rendered as PNG images (y/N) [n]: n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]: n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
> Create Makefile? (Y/n) [y]: n
> Create Windows command file? (Y/n) [y]: n
正常に実行されると、プロジェクトのdoc / sourceディレクトリにあるconfig.pyファイルを見つけることができます。このファイルは、以下のようにビルドコマンドを実行すると、ドキュメントの生成方法の基本的な構造を制御します
$ sphinx-build -b html sourcedir builddir
詳しい手順はhttps：//pythonhosted.org/an_example_pypi_project/sphinx.htmlを参照してください。