sphinx入門ガイド【1】クイック入門
3328 ワード
概要
sphinxはドキュメントを迅速に生成するためのツールで、Pythonドキュメントを生成するのに非常に適しています.
次のようなメリットがあります.はhtml、Latex、ePubなど、さまざまな出力フォーマットをサポートします. 豊富な拡張 構造化文書 自動インデックス 構文ハイライト をサポート
sphinxは、そのタグ言語としてreStructuredtextを使用します.
インストール
pipを使用してインストールするには、次の手順に従います.
ソースファイルディレクトリの設定
含む.rstファイルのルートディレクトリはソースファイルディレクトリと呼ばれ、ディレクトリにはsphinxのプロファイルconf.pyも含まれています.
ソース・ファイル・ディレクトリにアクセスし、次のコマンドを実行すると、ユーザーにプロジェクト全体の構成を指示します.
ファイル構造の定義
上記のコマンドを実行すると、sphinxはソースファイルディレクトリにconf.pyファイルおよびindexを自動的に生成する.rst.index.rstはメインドキュメントと呼ばれ、sphinxがウェルカムページとして使用されます.
index.rstにはディレクトリツリーコマンドtoctreeが含まれており、sphinxはそれを使用して他のサブドキュメントをリンクします.
toctree命令の初期値は空です.
次に、サブドキュメントのリンクを追加して、ドキュメントの名前を直接使用すればいいので、ファイル接尾辞を省略し、マルチレベルディレクトリであれば、使用/分割します.
次に、上記のファイルを作成し、対応する内容を追加することができます.sphnixは、これらのドキュメントの章タイトルをdoctreeコマンドの場所に自動的に挿入します.
コンテンツの追加
sphinxソースファイルでは、reStructuredTextタグ言語を使用してドキュメントを記述するほか、sphinxでは特にいくつかのコマンドが提供されています.
具体的には
reStructuredText PrimerおよびSphinx Markup Constructs
ドキュメントの生成
次のコマンドを使用して、ドキュメントを生成します.
sourcedirはソースファイルディレクトリを指し、生成されたドキュメントはbuilddirで指定されたディレクトリに配置されます.
実際にはもっと簡単な方法があり、sphinx-quickstartはmakeを生成した.batファイル、このスクリプトを直接実行できます.
上記のコマンドは、ソースファイルディレクトリに直接ドキュメントを生成します.
オブジェクトドキュメント
sphinxの設計の目的の1つは、任意のドメイン内のオブジェクトのドキュメントを生成しやすくすることであり、ドメインは多くのオブジェクトの集合を指し、これらのオブジェクトには対応するドキュメントコメントも含まれている.
最も主要なドメインはPythonドメインです.例えばpython内蔵関数enumerate()のコメントドキュメントは次のようになります.
次の形式でレンダリングされます.
enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the sequence. (And so on.) 命令パラメータは、ドキュメントの注釈を記述する必要があるオブジェクトです.Pythonはデフォルトのドメインであるため,属するドメインを特に指摘する必要はない.
sphinxはまた、他のオブジェクトタイプのドキュメントを生成するためのいくつかの命令を提供します.例えば
sphinxはconf.pyで構成され、conf.pyはpython構文を使用し、デフォルトではutf-8符号化で保存されます.詳細については、The build configuration fileを参照してください.
ドキュメントコメントの自動生成
sphinxはpythonソースコードからドキュメントコメント情報を抽出し、ドキュメントを生成することをサポートします.これをautodocと呼びます.
Autodocを使用するには、まずプロファイルのextensionsオプションに'sphinxを追加する必要があります.ext.autodoc'.そしてautodocのコマンドを使用することができます.
例えば、関数ioを生成する.Open()のドキュメントは、rstファイルに次の文を追加するだけです.
クラス全体のドキュメントを直接生成することもできます.
ドキュメントのコメントを抽出するには、autodocがコメントをインポートするモジュールが必要です.だからsys.pathにモジュールのパスを設定します.
テーマの設定
readthedocで使うテーマをお勧めします.美しくて簡潔で気前がいいです.まず、トピックライブラリをインストールします.
次にconf.pyを構成します.
sphinxはドキュメントを迅速に生成するためのツールで、Pythonドキュメントを生成するのに非常に適しています.
次のようなメリットがあります.
sphinxは、そのタグ言語としてreStructuredtextを使用します.
インストール
pipを使用してインストールするには、次の手順に従います.
pip install sphinx
ソースファイルディレクトリの設定
含む.rstファイルのルートディレクトリはソースファイルディレクトリと呼ばれ、ディレクトリにはsphinxのプロファイルconf.pyも含まれています.
ソース・ファイル・ディレクトリにアクセスし、次のコマンドを実行すると、ユーザーにプロジェクト全体の構成を指示します.
sphinx-quickstart
ファイル構造の定義
上記のコマンドを実行すると、sphinxはソースファイルディレクトリにconf.pyファイルおよびindexを自動的に生成する.rst.index.rstはメインドキュメントと呼ばれ、sphinxがウェルカムページとして使用されます.
index.rstにはディレクトリツリーコマンドtoctreeが含まれており、sphinxはそれを使用して他のサブドキュメントをリンクします.
toctree命令の初期値は空です.
.. toctree::
:maxdepth: 2
次に、サブドキュメントのリンクを追加して、ドキュメントの名前を直接使用すればいいので、ファイル接尾辞を省略し、マルチレベルディレクトリであれば、使用/分割します.
.. toctree::
:maxdepth: 2
intro
tutorial
chapter/doc1
...
次に、上記のファイルを作成し、対応する内容を追加することができます.sphnixは、これらのドキュメントの章タイトルをdoctreeコマンドの場所に自動的に挿入します.
コンテンツの追加
sphinxソースファイルでは、reStructuredTextタグ言語を使用してドキュメントを記述するほか、sphinxでは特にいくつかのコマンドが提供されています.
具体的には
reStructuredText PrimerおよびSphinx Markup Constructs
ドキュメントの生成
次のコマンドを使用して、ドキュメントを生成します.
$ sphinx-build -b html sourcedir builddir
sourcedirはソースファイルディレクトリを指し、生成されたドキュメントはbuilddirで指定されたディレクトリに配置されます.
実際にはもっと簡単な方法があり、sphinx-quickstartはmakeを生成した.batファイル、このスクリプトを直接実行できます.
make html
上記のコマンドは、ソースファイルディレクトリに直接ドキュメントを生成します.
オブジェクトドキュメント
sphinxの設計の目的の1つは、任意のドメイン内のオブジェクトのドキュメントを生成しやすくすることであり、ドメインは多くのオブジェクトの集合を指し、これらのオブジェクトには対応するドキュメントコメントも含まれている.
最も主要なドメインは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 index and an item of the sequence. (And so on.) 命令パラメータは、ドキュメントの注釈を記述する必要があるオブジェクトです.Pythonはデフォルトのドメインであるため,属するドメインを特に指摘する必要はない.
.. function:: enumerate(sequence[, start=0])
...
sphinxはまた、他のオブジェクトタイプのドキュメントを生成するためのいくつかの命令を提供します.例えば
py:class及びpy:method基本構成sphinxはconf.pyで構成され、conf.pyはpython構文を使用し、デフォルトではutf-8符号化で保存されます.詳細については、The build configuration fileを参照してください.
ドキュメントコメントの自動生成
sphinxはpythonソースコードからドキュメントコメント情報を抽出し、ドキュメントを生成することをサポートします.これをautodocと呼びます.
Autodocを使用するには、まずプロファイルのextensionsオプションに'sphinxを追加する必要があります.ext.autodoc'.そしてautodocのコマンドを使用することができます.
例えば、関数ioを生成する.Open()のドキュメントは、rstファイルに次の文を追加するだけです.
.. autofunction:: io.open
クラス全体のドキュメントを直接生成することもできます.
.. automodule:: io
:members:
ドキュメントのコメントを抽出するには、autodocがコメントをインポートするモジュールが必要です.だからsys.pathにモジュールのパスを設定します.
テーマの設定
readthedocで使うテーマをお勧めします.美しくて簡潔で気前がいいです.まず、トピックライブラリをインストールします.
pip install sphinx_rtd_theme
次にconf.pyを構成します.
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]