[備忘録]docstringから, 「美ドキュメント」を自動生成する.

##やること
自作の関数とかのドキュメントをdocstring(numpyスタイル)からSphinxを用いて自動生成する.

##なんでやるの

• 一般に公開するプロジェクトで必要になった
• あとで自分が見返せる様に
• numpyスタイルで生成してる記事が少ない気がした

##やっていく
###numpyスタイルの復習
必須なものだけまとめる, 詳細はこちらを参考にさせていただきました.

• docstringはclassや関数の直下に"""で始め"""で終わる.
• 詳細を始めに書き1行空けた後, 各引数など内容を記述する.

####classの例

.py

class Tag(object):
    """
    各属性値やヘルパー関数を保持する

    Attributes
    ----------
    id : int
        対象のマスタID
    name : str
        名前
    price_dict : dict
        キーに地域のID、値に該当する地域での値段を保持した辞書.
    """

    def __init__(self, id):
        """
        Parameters
        ----------
        id : int
            対象のマスタID.
        """
        self.id = id
        self.name = self.get_name(id=id)
        self.price_dict = self.get_price_dict(id=id)

    def get_name(self, id):
        # ...内容省略.
        pass

    def get_price_dict(self, id):
        # ...内容省略.
        pass

####関数の例

• より詳細な説明を入れる場合もう1行空けて書く
• その後にまた1行空けて各引数の記述をする

.py

def dfma_buy_function(period=25, buy_threshold=-1, method="simple", __ops = lambda a,b: a < b, target_column = "close_price_adj"):
  '''
　dfma:移動平均線乖離率分析　#ここに概要

  詳細な説明：指定した割合よりも平均線から乖離したら買いシグナルを出します.

  Parameters
  ----------
  period : int
    どの期間の移動平均を取るか
  buy_threshold : float
    どれ位平均線から下回ったら買うかの境界,割合 ex. -2 = 2%下回っている
  method : string
    どの平均を用いるかexpo:指数平滑平均,simple:単純移動平均,weighted:加重平均（デフォルトは単純）
  __ops : function
    どの比較演算子を用いるかlambdaで受けとる, >:より大きい, >=:以上, ==:等価, <=:以下, <:より小さい
  target_column : string
    利用する価格データのcolumn(default: close_price_adj)
    
  Returns
  ----------
  emitter_function: func
    (この指標における計算された値と売買の閾値の"DFMA:g","buy:sig")を返す関数を返す
  '''
 #(内容省略)
  return _my_signal

###Sphinxの用意
今回はOSX, condaの仮想環境上でインストールした.

(docstring) mac:~ User$ conda install Sphinx

###目指すディレクトリ構成

VisualCoding
|- docs              #ページを編集するためのファイルとかある
|- maron-signalfunc　#ドキュメントを作りたいモジュールファイルとかある
|  |- dfma.py
|  |- rsi.py
|  |-...
|- html              #htmlファイルが書き込まれる

###スタート
####最初のディレクトリ構成
別に最初からdocs, htmlディレクトリ(中身空)作っておいても良し

VisualCoding
|- maron-signalfunc　#ドキュメントを作りたいモジュールファイルとかある

####.rstファイルなどの作成
ページを編集するための.rstファイルをdocディレクトリに作成する.

(docstring) mac:VisualCoding User$ sphinx-apidoc -F -o ./docs ./maron-signalfunc

実行後のファイル構成

VisualCoding
|- docs              #ページを編集するためのファイルとかある
|  |- modules.rst    #moduleの追加削除したらこれを編集する
|  |- index.rst      #トップページの編集をする
|  |- conf.py        #ドキュメントのテーマとかAuthorの設定が出来る
|  |-...
|- maron-signalfunc　#ドキュメントを作りたいモジュールファイルとかある

####.htmlファイルの作成
conf.pyの設定をする.

conf.py

#...（中略）
# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# 以下三行のコメントアウト(#)を外す
import os
import sys
sys.path.insert(0, '/User依存の所/VisualCoding/maron-signalfunc')


# -- Project information -----------------------------------------------------
# project名とかイキった名前を付ける.
project = 'maron-signalfunc'
copyright = '2019, Author'
author = 'Author'

# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''

#（中略）...

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
# ここでテーマを変えられるデフォはalabasterだがsphinx_rtd_themeの方が好き
html_theme = 'sphinx_rtd_theme'

#（中略）...

.htmlファイルをhtmlディレクトリ内に生成する

(docstring) mac:VisualCoding User$ sphinx-build -a ./docs ./html

実行後のファイル構成

VisualCoding
|- docs              #ページを編集するためのファイルとかある
|- maron-signalfunc　#ドキュメントを作りたいモジュールファイルとかある
|- html
   |- index.html #メインページ？開くと綺麗にできてるはず.
   |- ...

完成

dfma.htmlを開いてみる.

いい感じ

##付録：Sphinxのコマンドoption
こちらから引用させていただきました.
###sphinx-apidoc

オプション	動作
-F	fullで生成. 指定しない場合はrstファイルのみ生成.
-f	出力時に強制上書き.
-o	出力先を指定
-H	プロジェクト名を指定.
-A	authorを指定.
-V	versionを指定.

###sphinx-build

オプション	動作
-b	ビルダー（≒出力形式）を指定.デフォルトではhtml, xml,latexなどを指定することができる.
-a	すべての出力ファイルを書き出す. このオプションをつけない場合は新規に作成されたり,変更のあったソースファイルに関連する出力ファイルだけを出力する.

##参考資料
以下のサイトを参考にさせて頂きました.

• [Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル）
• sphinx入門 その1 ドキュメントの自動生成