スタート

ライオンの顔は 文書生成器 あるいは，1組の平文素ファイルを様々な出力フォーマットに変換するツールであり，交差引用，インデックスなどを自動生成する. RedTextを再構築する あるいは…。 減記する. 文書，Sphinxは，一連のHTML文書，PDFファイル(LaTeXによる)，マニュアルページなどを生成することができる.

Sphinxは文書、特に手書き文書に集中しているが、Sphinxはブログ、ホームページ、さらには書籍を生成するためにも使用することができる。Sphinxの機能の大部分は、デフォルトのプレーンテキストマークフォーマットの豊富さから来ている。 reStructuredText そしてその significant extensibility capabilities それがそうです。

本文書の目標は、Sphinxとそれがどのように使用されているのかを迅速に理解することです。ここの仕事が終わったら見ることができます installation guide 次に、Sphinxが使用するデフォルトタグフォーマットについて説明します。 reStucturedText それがそうです。

一般的に書かれている文書の優れた“紹介”については，なぜ文書を作成するかについては，参照されたい `Write the docs`_ エリック·ホルシェールが書いています

文書源を設置する.

純文本稿の文書元のSphinx集合の根リストを呼ぶ source directory それがそうです。このディレクトリにはSphinxプロファイルも含まれています conf.py Sphinxがソースコードを読み取り、文書方式を構築する様々な態様を構成することができます。 1

Sphinxにはスクリプトが付いています sphinx-quickstart これにより、ソースディレクトリが設定され、デフォルトディレクトリが作成されます。 conf.py それはあなたにいくつかの質問をします。その中には最も有用な構成値が含まれています。このコマンドを使用するには、以下のコマンドを実行してください。

$ sphinx-quickstart

文書構造を定義する

あなたが実行したと仮定しましょう sphinx-quickstart それがそうです。以下のコマンドを使用してソースディレクトリを作成します conf.py そして主文書は index.rst それがそうです。主要な機能を持っています master document 歓迎ページとして使用され、“ディレクトリツリー”のルート(または 三叉の木 ）。これは，SphinxをreStrinredTextに追加する主な機能の1つであり，複数のファイルを単一の文書階層構造に接続する方法である.

ReStructiredTextコマンド

toctree ReStrstrucredTextです directive これは非常に汎用的なマークです指示はパラメータ、オプション、そして内容を持つことができる。

立論. 指示名の後ろの二重コロンの後に続く。各指示はそれがパラメータを持つことができるかどうか、いくつのパラメータを持つことができるかを決定する。

オプション パラメータの後に“フィールドリスト”の形で与えられる.♪the maxdepth このような選択は toctree 指令する。

内容 空行の後に続くオプションやパラメータの後。各指示は内容を許可するかどうか、内容をどのように処理するかを決定する。

指示の一般的な問題は コンテンツの1行目はオプションと同じレベルにインデントしなければならない それがそうです。

♪the toctree コマンドは最初は空であり，以下のようになる.

.. toctree::
   :maxdepth: 2

リストされた文書を追加することができます 内容 このコマンドの内容は以下のとおりである.

.. toctree::
   :maxdepth: 2

   usage/installation
   usage/quickstart
   ...

だから toctree 本文書については、参照されたい。含まれるファイルは以下のとおりである document name s、簡単に言うと、ファイル拡張子を使用するのではなく、正のスラッシュを使用することを意味します。 (/ )をディレクトリ区切りとして使用します。

more info もっと多くのことを読んで the toctree directive それがそうです。

今では、あなたがいることを作成することができます toctree そして、それらの章タイトルが挿入されるコンテンツを追加します(最大可達 maxdepth レベル)の位置 toctree 指示は置かれた。また，Sphinxは現在文書の順序や階層構造を知っている.(それらには toctree 指示自体、これは必要であれば、深さ入れ子の階層構造を作成することができることを意味します。)

内容を追加する

Sphinxソースファイルでは、標準的なほとんどの機能を使用することができます reStructuredText それがそうです。Sphinxにはいくつかの機能が追加されている.方法は、ファイル間参照(すべての出力タイプに適用可能)を移植可能な方法で追加する。 ref 役。

例えば、HTMLバージョンを見ている場合には、サイドバーの“Show Source”リンクを使用して、その文書のソースコードを見ることができます。

課題

これらのガイドに新しいガイドを追加する場合は、以下のリンクを更新してください。

more info 見 RedTextを再構築する Sphinxによって追加されたタグを含むreStrinredTextをより深く紹介することができる。

運行構築

もうあなたはいくつかのファイルと内容を追加して、私たちが最初に文書を構築しましょう。生成は sphinx-build 計画：

$ sphinx-build -b html sourcedir builddir

どこだ？ ソースディレクトリ. はい。 source directory そして、 ディレクトリを構築する 構築された文書を置くディレクトリである.♪the -b オプションは1つのビルダを選択し、本例では、SphinxはHTMLファイルを構築する。

more info 参考にする sphinx-build man page 以下の条件を満たすすべてのオプションについて sphinx-build 支えて。

しかし sphinx-quickstart スクリプトを作成します Makefile 1つと make.bat これはあなたの生活をもっと楽にします。これらのコマンドは、以下のコマンドを実行することで実行することができます make 建造者の名前が書いてある。例えば。

$ make html

これにより、選択された構築ディレクトリにHTML文書が構築されます。執行する． make どの目標が利用可能かを見るためのパラメータはありません。

PDF文書はどのように生成されますか？

make latexpdf 運行 LaTeX builder PdfTeXツールチェーンをいつでもお呼びします。

課題

RSTまたは命令に関するガイドに部分的に移行する

記録対象

Sphinxの主な目標の1つは簡単に記録することです objects (非常に一般的な意味で)どのような意味でも domain それがそうです。ドメインは一緒に属するオブジェクトタイプの集合であり，これらのオブジェクトの記述を作成して参照するためのタグを持つ.

最も顕著な領域はPythonドメインだ。例えばPythonの内蔵関数を記録するには enumerate() ソースファイルに追加することができます。

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

そのレンダリング方式は以下のとおりである.

enumerate(sequence[, start=0])

インデックスのタプルと、インデックスのタプルとを生成する反復器に戻る 配列 それがそうです。(以下同様。)

このコマンドのパラメータは signature あなたが説明したオブジェクトの中で、内容はその文書です。各署名は自分の行にある複数の署名を提供することができる。

Pythonドメインもちょうどデフォルトドメインなので、マークの前にドメイン名を追加する必要はありません。

.. function:: enumerate(sequence[, start=0])

   ...

デフォルトドメインのデフォルト設定が保持されている場合、同じ動作が実行される。

他のタイプのPythonオブジェクトを記録するためのコマンドもいくつかあります例えば py:class あるいは…。 py:method それがそうです。もう一つ相互参照の role これらのオブジェクトタイプのそれぞれについて.このタグは，文書へのリンクを作成する. enumerate() それがそうです。

The :py:func:`enumerate` function can be used for ...

これが証拠ですリンクは enumerate() それがそうです。

もう一度言ってみると py: Pythonドメインがデフォルトドメインである場合は省略することができる.どの文書に含まれる実際の文書は重要ではない enumerate() ライオンの顔画像はそれを見つけてそれへのリンクを作成します

各ドメインは、署名の外観に関する特殊なルールを有し、フォーマットされた出力をきれいに見せるか、またはパラメータタイプのリンク、例えばC/C++ドメインのような特定の機能を追加する。

more info 見 網域. すべての利用可能なドメインとその指示/役割。

基本構成.

先ほどお話ししたように conf.py ファイルはSphinxが文書を処理する方式を制御する.Pythonソースファイルとして実行されるファイルには、構成値を割り当てることができます。上級者：Sphinxによって実行されるので、拡張のような重要なタスクを実行することができます sys.path または、あなたが記録しているバージョンを見つけるためにモジュールを導入します。

変更したい構成値はすでに入っているかもしれません conf.py vt.から. sphinx-quickstart 最初に注釈しました(標準Python文法を使用して：a # その行の残りの部分を注釈する).デフォルト値を変更するには、ハッシュ記号を削除してその値を修正してください。自動的に追加されない構成値をカスタマイズするには、以下の操作を実行してください sphinx-quickstart 追加の作業を追加すればいいです。

このファイルは文字列、数字、リストなどにPython文法を使用していることを覚えておいてください。デフォルトの場合、ファイルは、第1の行の符号化宣言によって示されるように、UTF−8フォーマットで保存される。

more info 見 配置 利用可能な構成値のすべての文書を取得します。

課題

文書全体を他の部分に移動させる

自動ドッキング.

Pythonコード文書を作成する際には、通常、ソースファイルや文書文字列に大量の文書が置かれます。Sphinxは使用をサポート extension (拡張は、Sphinxプロジェクトに追加機能を提供するPythonモジュールです)、名前は 自動ドッキング. それがそうです。

使用するために 自動ドッキング. 中で活性化する必要があります conf.py ロープを 'sphinx.ext.autodoc' 割り当てに追加する extensions 構成値：：

extensions = ['sphinx.ext.autodoc']

そして、あなたはいくつかの追加的な指示を使用することができる。例えば関数を記録するには io.open() ソースファイルからその署名および文書文字列を読み取り、以下のコードを作成します。

.. autofunction:: io.open

AUTOコマンドのメンバーオプションを使用して、クラス全体、またはモジュールを自動的に記録することもできます。例えば、：

.. automodule:: io
   :members:

自動ドッキング. 文書文字列を抽出するためにはモジュールを導入する必要がある.したがって、適切な経路を追加しなければなりません sys.path あなたの conf.py それがそうです。

警告

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

スクリプト(ライブラリモジュールとは反対)を記録した場合、メインルーチンが受けることを確認してください if __name__ == '__main__' 条件

more info 見 sphinx.ext.autodoc AutoDoc機能の完全な説明については、参照されたい。

課題

この文書を別のパーティションに移動させます

獅子面像

Sphinx文書の多くは Python documentation インターネット上に発表されていますこのような文書を文書からリンクしたい場合には、ご利用いただけます sphinx.ext.intersphinx それがそうです。

Intersphinxを使用するためには、中でそれを活性化する必要があります conf.py ロープを 'sphinx.ext.intersphinx' 入る extensions 一覧して設定する intersphinx_mapping 値を配置する。

例えばリンクするには io.open() Pythonライブラリマニュアルでは、設定する必要があります intersphinx_mapping 好き：：

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

クロス引用を書くことができます :py:func:`io.open .中で構成された文書セットは、現在の文書セットで一致していない任意の交差参照を検索する :confval:`intersphinx_mapping (有効なターゲットリストをダウンロードするためにはURLにアクセスする必要があります)。Intersphinxは他のいくつかにも適用されます domain 役割には :ref: しかしそれは適用されません :doc: これは非領域的な役割だからです

more info 見 sphinx.ext.intersphinx Intersphinx特徴の完全な記述については、参照されたい。

より多くのテーマをカバーしなければならない

脚注

1

これは通常のレイアウトです。しかし conf.py 別のディレクトリに配置することもできます configuration directory それがそうです。参考にする sphinx-build man page より多くの情報を得ることができます