[비망록] docstring에서 자동으로'미 문서'를 생성합니다.

8697 단어 Python3 Sphinx docstring Python

할 일

docstring (numby 스타일) 으로 자동 함수 같은 문서를 생성합니다.

왜?

일반 공개 프로젝트에 필요

나중에 자신을 볼 수 있도록

numby 스타일로 만들어진 글이 적은 것 같아

계속하다

복습

필요한 것만 모으고 자세한 내용은 여기.을 참고하세요.
docstring은class나 함수의 바로 아래에서 ""로 시작하고 "로 끝납니다.

상세한 내용을 쓰기 시작한 후 한 줄을 비운 후 각 매개 변수 등의 내용을 기술한다.

class의 예

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

함수 예

더 자세한 설명이 필요하면 한 줄을 비워 쓰십시오

그리고 각 매개 변수를 설명하기 위해 한 줄을 비운다

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,} 디렉터리를 만들 수도 있습니다(중신공)

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　#ドキュメントを作りたいモジュールファイルとかある

서류 제작

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 디렉터리에 파일 생성

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

실행 후 파일 구성

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

완성