從PEP8編寫的Python文檔中創建API

我已經用Python編寫了一個代碼。我試圖遵循有關在函數開始時編寫有用註釋的常見準則。我的風格是PEP8，例如從PEP8編寫的Python文檔中創建API

def __init__(self, f_name=None, list_=None, cut_list=None, n_events=None, description=None): 
     """ 
     Parse an LHCO or ROOT file into a list of Event objects. 

     It is possible to initialize an Events class without a LHCO file, 
     and later append events to the list. 

     Arguments: 
     f_name -- Name of an LHCO or ROOT file, including path 
     list_ -- A list for initalizing Events 
     cut_list -- Cuts applied to events and their acceptance 
     n_events -- Number of events to read from LHCO file 
     description -- Information about events 
     """

我想從我的代碼自動生成有用的API。我找到了幾個選擇，特別是在看獅身人面像。它似乎做我想做的事情（雖然我努力使它產生一個API，而不是我的程序手冊）。缺點，然而，它有文檔字符串它自己的預期風格：

""" 
:param x: My parameter 
:type x: Its type 
"""

是不是真的對我最好重寫我的這個語法的所有文檔字符串？他們產生了一個很好的API，但是我不喜歡他們在代碼中，如果事實證明這是一個糟糕的主意，它會很耗時。什麼是標準，最佳實踐？我應該轉換嗎？如果是這樣，可以自動爲我做些什麼？

來源

2015-10-15 innisfree

文檔字體的Sphinx默認格式非常強大，如果您想要生成乾淨的API文檔，並且需要在幾個月，幾年中查看自己的代碼，那麼這絕對是值得的。所以是的，這是一個好主意。

如果你不喜歡默認的獅身人面像，其餘的語法，你可以嘗試寫你的文檔字符串the way Numpy do，如：

def func(arg1, arg2): 
    """Summary line. 

    Extended description of function. 

    Parameters 
    ---------- 
    arg1 : int 
     Description of arg1 
    arg2 : str 
     Description of arg2 

    Returns 
    ------- 
    bool 
     Description of return value 

    """ 
    return True

有一個獅身人面像的擴展名（Napoleon），它允許獅身人面像解析這種風格（或谷歌風格，這更簡單）。

來源

2015-10-15 08:06:42 Leo

我認爲Sphinx語法非常輕巧（很高興它不是Javadoc），所以就非常原始的代碼而言，它不是一個嚴重的缺點。

當我將一個文檔字符串添加到函數中時，我的IDE PyCharm會自動創建Sphinx樣式的骨架。因此，有些開發人員對Python有一些瞭解（並且也喜歡在其他領域推廣PEP8風格），並推薦Sphinx。 PyCharm甚至有一個用於推理和類型檢查的類型提示系統，它通過檢查文檔字符串中的聲明開始。

這是您可以用來自動進行轉換的正則表達式。替換

^(\s+)(\w+) -- (.+)$

與

$1:param $2: $3\n$1:type $2:

$n其中表示第n組。當然，你需要自己填寫這個類型。

來源

2015-10-15 08:09:00

+10 for PyCharm – Leo

從PEP8編寫的Python文檔中創建API

回答

相關問題