Help us understand the problem. What is going on with this article?

Sphinxの使い方.docstringを読み込んで仕様書を生成

更新履歴

  • 2020年7月19日 Sphinx v3.1.2を基準とした記述に変更しました

Sphinxとは

Sphinxは知的で美しいドキュメントを簡単に作れるツールです.
公式が自称しています)

例えば,下のようなドキュメントが,pythonのソースコードから生成できます.

2018-09-02_23h31_08.png

以下,このようなドキュメントの生成手順を解説します.

環境

  • Windows 10
  • Python 3.6
  • Sphinx 3.1.2

※Mac, Linuxでも動作しました

Sphinxのインストール

PyPIから

$ pip install sphinx

condaから

$ conda install sphinx

これで,いくつかのsphinxコマンド(sphinx-apidoc,sphinx-autogen,sphinx-build,sphinx-quickstart)が使えるようになります.

ドキュメントを抽出したいpythonファイルの準備

main.pyを作り,以下を記述します.

"""で囲まれた部分がdocstringと呼ばれる部分で,クラスやメソッドの注釈を入れることができます.

docstringの記法にはReStructuredTextスタイル,Numpyスタイル,Googleスタイルなどがありますが,今回はGoogleスタイルで書きます.

main.py
class TestClass:
    """Summary line.
    """

    def testfunc(self, x, y):
        """sum

        Args:
            x (int): 1st argument
            y (int): 2nd argument

        Returns:
            int: sum result

        Examples:
            >>> print(testfunc(2,5))
            7
        """
        return x + y

記法に関しては下記を参照.

プロジェクトの準備

作業ディレクトリを作成し,以下のようにディレクトリを構成して先ほどのmain.pyを配置します.

.
├── docs
└── main.py

sphinx-quickstartを使ってプロジェクトを作成します.
コマンドラインで次のコマンドを入力します.

$ sphinx-quickstart docs

(引数で指定されたdocs内に,ファイルが自動生成されます.)

すると,対話形式で質問がきます.

> Separate source and build directories (y/n) [n]:

ソースとビルドのディレクトリを完全に分けるかどうか.
デフォルトだとソースフォルダ内に_buildディレクトリができます.
そのままエンター.

> Project name: hoge
> Author name(s): hogehoge

プロジェクトと作者の名前.
この2つだけは入力しないと Please enter some text. と怒られるので,適当に入力します.

> Project release []:

プロジェクトのバージョン.
1.0.0など,好きなように入力.エンター.

> Project language [en]:

jaで日本語を指定できますが,最終的なドキュメントがあまり好みではなかったので,デフォルトのenでいきます.
何も入力せずエンター.

enのままでも日本語は使えて,docstring内で日本語を使ってもエラーにはなりません)

対話は以上で,この時点で,以下のディレクトリ構成とファイルが生成されます.

.
└── docs
    ├── Makefile
    ├── _build
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    └── make.bat

conf.pyはこれからドキュメントを生成していく上での設定値が格納されています.

index.rxtはトップページを提供し、toctreeと呼ばれるスクリプトが記述されています.toctreeは複数のファイルを単一の階層構造に結びつける役割を持っています.

make.batはwindowsでhtmlを生成するときに使用しますが,この記事ではコマンドラインからhtmlを生成するコマンドを打つので今回は気にしなくて大丈夫です.

Sphinx v1.x 使用時のチェック項目も記載しています.参照するには矢印をクリックして展開してください.
> Separate source and build directories (y/n) [n]:

ソースとビルドのディレクトリを完全に分けるかどうか.
デフォルトだとソースフォルダ内に_buildディレクトリができます.
そのままエンター.

> Name prefix for templates and static dir [_]:

Sphinxの作るシステムディレクトリの名前の先頭に付く文字列の指定.デフォルトだと_
そのままエンター.

> Project name: hoge
> Author name(s): hogehoge

プロジェクトと作者の名前.
この2つだけは入力しないと Please enter some text. と怒られるので,適当に入力します.

> Project release []:

プロジェクトのバージョン.
1.0.0など,好きなように入力.エンター.

> Project language [en]:

jaで日本語を指定できますが,最終的なドキュメントがあまり好みではなかったので,デフォルトのenでいきます.
何も入力せずエンター.

enのままでも日本語は使えて,docstring内で日本語を使ってもエラーにはなりません)

> Source file suffix [.rst]:

ソースファイルのデフォルトの拡張子.デフォルトだと.rst.(reStructuredTextの記法によるテキストファイル,という意味).
そのままエンター.

> Name of your master document (without suffix) [index]:

ドキュメントを生成したときの,トップページのファイル名.デフォルトはindex
エンター.

> Do you want to use the epub builder (y/n) [n]:

エンター.

> autodoc: automatically insert docstrings from modules (y/n) [n]:

これはyでもいいのですが,どうせ後で設定ファイル(conf.py)を編集することになるので,そのままエンター.

> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: 
> viewcode: include links to the source code of documented Python objects (y/n) [n]: 
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: 
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

エンター連打.

conf.pyの編集

ドキュメント生成のための,最小限の設定をします.

読み込むpythonファイルの設定

docs/conf.pyを開き,以下のコードをコメントインします.

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

conf.pyから見て1つ上のディレクトリ内のpythonファイルを読み込むため,そのpath(../)を指定します.

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

拡張機能の設定

pythonコードのdocstringを読み込む設定をします.
conf.py内の

extensions = [
]

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'
]

にします.

sphinx.ext.autodocは,docstringを自動的に読み込むための拡張機能.

sphinx.ext.napoleonはNumpyスタイルかGoogleスタイルのdocstringをパースするための拡張機能です.
(これがないと,改行などがうまく反映されません)

index.rstの編集

後ほど,index.rstからトップページを生成することになります.

トップページで表示したいモジュール(今回はmain)をindex.rst内に追加しておきます.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   main

インデントに注意してください.
私の環境ではインデントが1つずれるだけでエラーになりました.

ドキュメントを生成する

まず,pythonファイルからrstファイルを生成します.
コマンドラインで次のコマンドを入力します.

$ sphinx-apidoc -f -o ./docs .

詳細は公式マニュアルを参照してください.

-fはファイルの上書きをONにする設定.
-oは出力先ディレクトリ(今回は./docs)の指定のための設定です.

次に,rstファイルからhtmlファイルを生成します.

$ sphinx-build -b singlehtml ./docs ./docs/_build

詳細は公式マニュアルを参照してください.

今回は単一ページのhtmlファイルを生成したかったので,-bオプションでsinglehtmlを指定しました.
htmlを指定することで,複数ページのhtmlファイルも生成できます.

docs/_build内にindex.htmlが生成されますので,ブラウザで開きます.

2018-09-02_23h30_07.png

これで最低限の文書ができました.

napoleonによるGoogleスタイルの読み込みの詳細は以下を参照してください:

Napoleon - Marching toward legible docstrings

タイトルを変える

index.rstを見ると,

.. hoge documentation master file, created by
   sphinx-quickstart on Sun Sep  2 18:45:37 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to hoge's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   main

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

のようになっていますので,この中の「Welcome to hoge's documentation!」を書き換えて,再度sphinx-buildするとindex.htmlに反映されます.

sphinx_rtd_themeを使う

htmlのデザインを変えてみます.

sphinx_rtd_themeをインストール

$ pip install sphinx_rtd_theme

conf.pyを開いて,html_themeを修正

html_theme = 'sphinx_rtd_theme'

再度sphinx-buildすると,一番上で掲載したようなhtmlファイルが生成されます.

最後に

仕様書が作成できたら,GitHubからWeb公開したり,CIによる自動ビルドなどが使えると便利です.これらについては既に素晴らしいまとめがありますのでご参照ください:

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした