sphinxクイックスタート

概要
sphinxはドキュメントを迅速に生成するためのツールで、Pythonドキュメントを生成するのに非常に適しています.
次のようなメリットがあります.

はhtml、Latex、ePubなど、さまざまな出力フォーマットをサポートします.

豊富な拡張

構造化文書

自動インデックス

構文ハイライト

をサポート
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()]

レターアドレス