sphinx-quickstartの起動

Sphinxのドキュメントセットを生成するのは、 sphinx-quickstart というプログラムです。これは次のように実行します:

$ sphinx-quickstart [options] [projectdir]

projectdir はSphinxドキュメンテーションディレクトリをあなたが配置したい場所に 設定します。もし projectdir を削除した場合、ファイルはデフォルトでは現在のディレクトリへ生成されます。

sphinx-quickstart スクリプトは次のようなオプションを持っています:

-q, --quiet

Quietモードはオプションを定義する対話式ウィザードをスキップします。このオプションは -p, -a および -v オプションを必要します。

-h, --help, --version

簡単な使い方やSphinxのバージョンを表示します。

構成オプション

--sep

記述した場合、ソースとビルドのディレクトリを分割します。

--dot=DOT

プロジェクトのルートディレクトリに 2以上のディレクトリが作成されます。カスタマイズしたHTMLテンプレート用の”_templates”ディレクトリと、カスタマイズしたスタイルシート等を置く”_static”ディレクトリがあります。これらのディレクトリは “_” で始まっていますが、別の文字(”.”など)で始まるように指定できます。

プロジェクトの基本オプション

-p PROJECT, --project=PROJECT

プロジェクト名を指定します ( project も参照)。

-a AUTHOR, --author=AUTHOR

著者名を指定します。 ( copyright も参照)。

-v VERSION

プロジェクトのバージョンを指定します ( version も参照)。

-r RELEASE, --release=RELEASE

プロジェクトのリリースを指定します ( release も参照)。

-l LANGUAGE, --language=LANGUAGE

ドキュメント言語。 ( language 参照 )

--suffix=SUFFIX

ソース・ファイルサフィックス。 ( source_suffix 参照)

--master=MASTER

マスタードキュメント名。 ( master_doc 参照)

--epub

epubを利用します。

拡張オプション

--ext-autodoc

sphinx.ext.autodoc 拡張を有効にします。

--ext-doctest

sphinx.ext.doctest 拡張を有効にします。

--ext-intersphinx

sphinx.ext.intersphinx 拡張を有効にします。

--ext-todo

sphinx.ext.todo 拡張を有効にします。

--ext-coverage

sphinx.ext.coverage 拡張を有効にします。

--ext-imgmath

sphinx.ext.imgmath 拡張を有効にします。

--ext-mathjax

sphinx.ext.mathjax 拡張を有効にします。

--ext-ifconfig

sphinx.ext.ifconfig 拡張を有効にします。

--ext-viewcode

sphinx.ext.viewcode 拡張を有効にします。

--extensions=EXTENSIONS

Enable arbitary extensions.

Makefileとbatファイルの生成オプション

--use-make-mode, --no-use-make-mode

Makefile/make.bat uses (or not use) make-mode. Default is use.

バージョン 1.5 で変更: make-mode is default.

--makefile, --no-makefile

makefileの作成 (もしくは非作成)

--batchfile, --no-batchfile

batファイルの作成 (もしくは非作成)

バージョン 1.3 で追加: sphinx-quickstartに複数の起動オプションを追加。

Project templating

-t, --templatedir=TEMPLATEDIR

Template directory for template files. You can modify the templates of sphinx project files generated by quickstart. Following Jinja2 template files are allowed:

  • master_doc.rst_t
  • conf.py_t
  • Makefile_t
  • Makefile.new_t
  • make.bat_t
  • make.bat.new_t

In detail, please refer the system template files Sphinx provides. (sphinx/templates/quickstart)

-d NAME=VALUE

Define a template variable

バージョン 1.5 で追加: Project templating options for sphinx-quickstart

sphinx-buildの起動

Sphinxのドキュメント群を生成するのは、 sphinx-build というプログラムです。これは次のように実行します:

$ sphinx-build [options] sourcedir builddir [filenames]

sourcedir には ソースディレクトリ が、 builddir にはビルドしたドキュメントを置きたいディレクトリを指定します。ほとんどの場合、 ファイル名 は指定する必要はありません。

sphinx-build スクリプトは次のようなオプションを持っています:

-b buildername

ビルダーを選択する、もっとも重要なオプションです。一般的に使用されるビルダーには次のような物があります。

html

HTMLページをビルドします。デフォルトのビルダーです。

dirhtml

HTMLページをビルドしますが、ドキュメントごとにディレクトリが生成されます。ウェブサーバで提供する場合に、 .html がURLに付かないようにして、URLが分かりやすくなります。

singlehtml

すべてのコンテンツが含まれる、単一のHTMLを生成します。

htmlhelp, qthelp, devhelp, epub

フォーマットごとに、ドキュメントのコレクションを構築するのに必要な情報と一緒に、HTMLファイルにビルドします。

applehelp

Apple Help Bookを生成します。オープンソースではありませんが、Mac OS X 10.6以降でのみ使用できる hiutilcodesign が必要になります。

latex

pdflatex を使用して、PDFドキュメントにコンパイルできるような、LaTeXのソースにビルドします。

man

UNIX系システムで利用される、groffフォーマットのmanページをビルドします。

texinfo

makeinfo を使ってInfoファイルを生成するための、Texinfoファイルにビルドします。

text

プレーンテキストファイルをビルドします。

gettext

gettextスタイルのメッセージカタログ(.pot ファイル)にビルドします。

doctest

もしも doctest 拡張が有効になっている場合には、ドキュメント内のすべてのdoctestを実行します。

linkcheck

すべての外部リンク先が存在しているか確認をします。

xml

Docutilsが生成するXMLファイルをそのまま出力します。

pseudoxml

コンパクトな整形された”pseudo-XML”を出力します。これは中間ドキュメントツリーの内部構造です。

Sphinxと一緒に提供されている、すべてのビルダーのリストは 利用可能なビルダー を参照してください。また、新しいビルダーを追加する拡張機能もあります。

-a

もしこのオプションが設定されると、すべての出力ファイルを書き出します。デフォルトでは新規に作成されたり、変更のあったソースファイルに関連する出力ファイルだけを出力します。このオプションはすべてのビルダーに適応するわけではありません。

-E

保存されている 環境 を使用しないで、完全に再構築する場合に利用します。環境にはクロスリファレンスの構造を保持しています。デフォルトでは新規に作成されたり、最後に実行してから変更のあったソースファイルだけを読み込んで、パースします。

-t tag

tag というタグを定義します。これは、タグが設定されているときにだけ内容を取り込むという、 only ディレクティブと関係があります。

バージョン 0.6 で追加.

-d path

Sphinxは出力ファイルが書き込むことが可能になる前に、すべてのソースファイルを読み込むため、パースされたソースファイルは “doctree pickles”と呼ばれるディレクトリにキャッシュされます。通常は、これらのファイルはビルドディレクトリの下の .doctrees と呼ばれるディレクトリに置かれます。このオプションを指定すると、キャッシュディレクトリを違う場所に設定できます。doctreeはすべてのビルダーで共有されます。

-j N

ビルドを N 個のプロレスで並列実行します。複数のCPUを搭載したコンピュータでより効率的にビルド出来るようになります。ただし、Sphinxの全てのビルダー・部分が並列実行されるわけではない事に注意して下さい。

バージョン 1.2 で追加: このオプションが 実験的 な機能であることに注意して下さい。

-c path

ソースディレクトリ以下の conf.py ではなく、オプションで指定されたコンフィグレーションディレクトリ以下の設定ファイルを利用するようにします。ただし、さまざまな他のファイル、パスなど、設定値で与えられたものに関しては、コンフィグレーションディレクトリからの相対パスで探索されることになるため、その状況になってもファイルがきちんと読めるようにしておく必要があります。

バージョン 0.3 で追加.

-C

コンフィグファイルを無視します。設定は -D オプションを使って指定します。

バージョン 0.5 で追加.

-D setting=value

conf.py ファイルで設定されたコンフィグを上書きします。この値は数値、文字列、リスト、もしくはディクショナリ型である必要があります。

リストについては、コンマ区切りで次のように要素を分けることができます: -D html_theme_path=path1,path2.

ディクショナリ型の値については、名前とキーを次のように与えます: -D latex_elements.docclass=scrartcl.

boolean型の値には、 0 もしくは 1 を使って下さい。

バージョン 0.6 で変更: 値に辞書型を指定出来るようになりました。

バージョン 1.3 で変更: 値にリスト型を指定出来るようになりました。

-A name=value

HTMLテンプレートの中の namevalue に設定します。

バージョン 0.5 で追加.

-n

エラーチェックが厳格なモードで実行されます。現在では、すべての見つからない参照に対して警告を生成するような実装になっています。 nitpick_ignore は警告する必要の無いものを除外する設定です。

-N

カラー出力をしません。

-v

表示の詳細度合い(ログレベル)を上げます。三回まで繰り返すことにより、ログ出力の詳細度合いが上がります。このオプションは暗黙のうちに -T を指定します。

バージョン 1.2 で追加.

-q

標準出力に何も出力しないようになります。警告やエラーのみが標準エラー出力に書き出されます。

-Q

標準出力に何も出力しないようになります。警告も抑制されます。エラーのみが標準エラー出力に書き出されます。

-w file

警告とエラーを指定されたファイルに書き出されます。なお、標準エラー出力にも同時に出力されます。

-W

警告をエラーにします。最初の警告でビルドが中断され、 sphinx-build が終了値1を返すようになります。

-T

捕捉されない例外が発生した時、完全なトレースバックを表示します。このオプションがない場合、要約だけが表示され、トレースバックの情報は今後の解析のためにファイルとして保存されます。

バージョン 1.2 で追加.

-P

(Sphinx自体のデバッグをする人用) キャッチされない例外がビルド中に発生したら、Pythonデバッガの pdb を実行します。

-h, --help, --version

簡単な使い方やSphinxのバージョンを表示します。

バージョン 1.2 で追加.

ソースディレクトリやビルドディレクトリの後ろにファイル名を1つ以上追加できます。追加すると、指定されたファイルと、その依存ファイルだけをビルドしようとします。

Environment variables

The sphinx-build refers following environment variables:

MAKE

A path to make command. A command name is also allowed. sphinx-build uses it to invoke sub-build process on make-mode.

Makefileオプション

sphinx-quickstart によって作成された Makefilemake.bat は通常、 sphinx-build-b および -d オプションだけで実行します。しかし、次のような変数を設定することで、動作をカスタマイズできます。

PAPER

latex_paper_size です。

SPHINXBUILD

sphinx-build の代わりに用いるコマンドです。

BUILDDIR

sphinx-quickstart で選択した以外のビルドディレクトリを使用します。

SPHINXOPTS

sphinx-build に設定する追加オプションです。

Deprecation Warnings

If any deprecation warning like RemovedInSphinxXXXWarning are displayed when building a user’s document, some Sphinx extension is using deprecated features. In that case, please report it to author of the extension.

To disable the deprecation warnings, please set PYTHONWARNINGS= environment variable to your environment. For example:

  • PYTHONWARNINGS= make html (Linux/Mac)
  • export PYTHONWARNINGS= をしてから、 make html を実行してください(Linux/Mac)

  • set PYTHONWARNINGS= をして ``make html``を実行してください (Windows)

  • modify your Makefile/make.bat and set the environment variable

sphinx-apidocの起動

The sphinx-apidoc generates completely automatic API documentation for a Python package. It is called like this:

$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

packagedir はドキュメント化したいパッケージのパス、 outputdir は生成されたソースが置かれる場所です。 pathnames は生成中に無視されるパスです。

警告

sphinx-apidoc はreSTファイルを生成し、 sphinx.ext.autodoc を使って、見つけた全てのモジュールをドキュメント化します。もしインポートによる副作用があれば、 sphinx-build が実行されるとき autodoc により実行されます。

もしあなたが (ライブラリモジュールではなく) スクリプトをドキュメント化したいのであれば、スクリプトのメインルーチンが if __name__ == '__main__' 条件により保護されていることを確認して下さい。

sphinx-apidoc スクリプトは次のようなオプションを持っています:

-o outputdir

ファイルを生成するディレクトリを指定します。

-f, --force

通常はsphinx-apidocはどんなファイルも上書きしません。このオプションを指定すると上書きするようになります。

-n, --dry-run

このオプションが与えられた場合は、いかなるファイルにも記述がなされません

-s suffix

このオプションにより出力ファイルのファイル拡張子を選択します。デフォルトでは rst です。

-d maxdepth

目次を生成する最大の深さを設定します。

-l, --follow-links

パッケージとモジュールを探すためにファイルシステムを再帰的に辿りますが、このオプションにより sphinx-apidoc はシンボリックも辿るようになります。 collective.recipe.omelette を使ったソースディレクトリからドキュメントを生成する場合に必要になります。デフォルトではシンボリックリンクは無視されます。

バージョン 1.2 で追加.

-T, --no-toc

このオプションをつけるとTOCファイルの modules.rst を生成しません。ただし、 --full オプションが渡された場合には無効となり生成されます。

-F, --full

このオプションをつけると sphinx-apidoc は sphinx-quickstart と同じように完全なSphinxプロジェクトを生成します。ほとんどの設定値はデフォルトに設定されますが、以下のオプションを使って最も重要な値を自分で設定出来ます。

--implicit-namespaces

By default sphinx-apidoc processes sys.path searching for modules only. Python 3.3 introduced PEP 420 implicit namespaces that allow module path structures such as foo/bar/module.py or foo/bar/baz/__init__.py (notice that bar and foo are namespaces, not modules).

Specifying this option interprets paths recursively according to PEP-0420.

-M

このオプションはサブモジュールドキュメンテーションの前にsphinx-apidocがモジュールドキュメンテーションを行うようにします。

-a

Append module_path to sys.path.

-H project

生成したファイルに含めるプロジェクト名を指定します ( project も参照)。

-A author

生成したファイルに含める著者名を指定します ( copyright も参照)。

-V version

生成したファイルに含めるプロジェクトのバージョンを指定します ( version も参照)。

-R release

生成したファイルに含めるプロジェクトのリリースを指定します ( release も参照)。