sphinxのテスト

2715 ワード

sphinxのテスト


chap 02 First Steps with Sphinx¶


このドキュメントは、クラスチュートリアルのプレビューを意味します.ここでの注釈は、より深く研究することを意味します.

2.1文書ソースの設定


ソースディレクトリと呼ばれるドキュメントセットのルートディレクトリ.このディレクトリにはSphinxのプロファイルconf.pyが含まれています.ここでは、Sphinxがソースを読み取り、ドキュメントを作成するようにさまざまな面を構成できます.
Sphinxはスクリプトでソースディレクトリを設定し、conf.pyを作成します.実行する限り:
$ sphinx-quickstart

そしてその質問に答えます.△すべて回答したことを確認します.

2.2文書構造の定義


まずSphinx-quickstartを実行したと仮定します.conf.pyとプライマリドキュメントindexを含むソースディレクトリを作成しました.rst(デフォルト値を受け入れる場合).プライマリ・ドキュメントの主な機能は、ディレクトリ(「table of contents tree」またはtoctree)を含むウェルカム・インタフェースを提供することです.これが主なことで、複数のファイルを整理します.
reStructuredText directives
toctree reStructuredText ,
 。
 , 。
 , 。
 ,
 。
 , ,
 。
 ,
 。
 。

toctreeコマンドは初期化時に空で、このように見えます.
.. toctree::
:maxdepth: 2

ドキュメントのリストを追加する必要があります.
.. toctree::
:maxdepth: 2
intro
tutorial
...

これがtoctreeが見える様子です.このドキュメントには、指定したドキュメントの名前が含まれますが、ドキュメントの接尾辞は使用せず、目次分割子としてスラッシュを使用します.
ファイルを作成してtoctreeに追加すると、章が挿入されます.Sphinxはあなたのドキュメントの構造と順序を知っています.(内部にtoctreeを含めることもできます.これは、より複雑な階層を作成できることを意味します.)

2.3内容を増やす。


Sphinxソースファイルでは、reStructuredTextの標準プロパティを多く使用できます.もちろん、Sphinxが増えているものもあります.例を挙げると、refを使用してクロスリファレンスを追加できます.
たとえば、HTMLバージョンを観察している場合は、サイドバーの「Show Source」をクリックしてソースコードを見ることができます.

2.4作成の実行


これで、ファイルとディレクトリを追加して、このドキュメントを初めて作成します.作成時に実行:
$ sphinx-build -b html sourcedir builddir

ここで、sourcedirはソースディレクトリであり、builddirは作成ドキュメントを保存する場所です.
オプション-bは、HTMLファイルを作成するbuilderを選択します.
しかし、sphinx-quickstartはmakefileとmakeを作成した.bat、そしてこのように呼び出すことができます.
$ make html

ターゲットファイルが作成されます.パラメータがmakeを実行していない場合は、使用可能なものを教えてくれます.

2.5文書オブジェクト/


Sphinxの主な目標の一つは,任意のdomainのobjectを簡略化することである.1つのdomainはオブジェクトタイプの集合であり、各オブジェクトを作成および参照するタグがあります.
その中で最も重要な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
] )

Return an iterator that yields tuples of an indexand an item of the sequence. (And so on.)
この命令のパラメータは、オブジェクトを記述する署名であり、内容は彼の記述である.複数の署名に対して、行ごとに1つを置くことができます.
Pythonはデフォルトのdomainなので、この接頭辞を置かずに表すことができます.
.. function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index
and an item of the *sequence*. (And so on.)