python中的pydoc

在終端上輸入pydoc會顯示以下信息

 

pydoc - the Python documentation tool

 

pydoc <name> ...

    Show text documentation on something.  <name> may be the name of a

    Python keyword, topic, function, module, or package, or a dotted

    reference to a class or function within a module or module in a

    package.  If <name> contains a '/', it is used as the path to a

    Python source file to document. If name is 'keywords', 'topics',

    or 'modules', a listing of these things is displayed.

 

pydoc -k <keyword>

    Search for a keyword in the synopsis lines of all available modules.

 

pydoc -p <port>

    Start an HTTP server on the given port on the local machine.  Port

    number 0 can be used to get an arbitrary unused port.

 

pydoc -b

    Start an HTTP server on an arbitrary unused port and open a Web browser

    to interactively browse documentation.  The -p option can be used with

    the -b option to explicitly specify the server port.

 

pydoc -w <name> ...

    Write out the HTML documentation for a module to a file in the current

    directory.  If <name> contains a '/', it is treated as a filename; if

    it names a directory, documentation is written for all the contents.

 

pydoc是python自帶的一個文檔生成工具，使用pydoc可以很方便的查看類和方法結構

python中pydoc模塊可以從python代碼中獲取docstring，然后生成幫助信息。

pydoc是Python自帶的模塊，主要用於從python模塊中自動生成文檔，這些文檔可以基於文本呈現的、也可以生成WEB 頁面的，還可以在服務器上以瀏覽器的方式呈現！

 

 

 

 

 python -m pydoc -p 1234     在本地機器上，按照給定的端口啟動HTTP

一、查看文檔的方法

方法1：啟動本地服務，在web上查看文檔

命令【python3 -m pydoc -p 1234】

 

通過http://localhost:1234來訪問查看文檔

 

說明：

1、-p指定啟動的服務的端口號，可以隨意指定不沖突的端口號

2、只有在自建的工程根目錄下使用該命令，才能看到當前工程下所有的內容，否則只能看到python環境變量下的模塊內容

3、如果本地只有一個python，可以直接使用【pydoc -p 端口號】啟動，但因為我本地有python2和python3，所以指定了用python3

方法2：直接查看某個py文件的內容 

例子：新建了一個py文件叫做testpydoc.py，進入testpydoc.py所在目錄

python3 -m pydoc testpydoc

 

 

方法三：生成html說明文檔

例子：新建了一個py文件叫做testpydoc.py，進入testpydoc.py所在目錄

python3 -m pydoc -w testpydoc

 

會默認將當前目錄下的testpydoc生成一個叫做testpydoc.html的文檔，如果是目錄直接【python3 -m pydoc -w 目錄名】生成文檔

 

說明：如果是將整個目錄生成這種格式，不建議用這種方式，因為如果他展示目錄下的子文件的說明時，會去子目錄下找對應.html文件，如果文件不存在，就會404

 

方法四：-k查找模塊

py通過-k查找模塊，會在當前工程目錄以及python環境變量目錄下查找包含關鍵詞的模塊信息 

【python3 -m pydoc -k 關鍵詞】

 

例如如下命令：

python3 -m pydoc -k  testpydoc

 

結果如下：

testpydoc - @author 每天1990

二、html文檔說明 

通過查看文檔的方法，我們可以看到在html的文檔主要分成四部分：py文件的頂部注釋、Classes、Functions、Data

（示例代碼見結尾部分）

第一部分：模塊的文檔說明，展示模塊頂部的多行注釋

注釋內如果包含了模塊文件內的class名，或方法名()，則顯示藍色，且可以點擊跳轉到對應說明位置

 

第二部分：classes，展示class以及class下的function

1.只能展示class下的注釋，不會展示class下方法的注釋

2.class上面有#注釋時，展示#號的注釋

3.class下有”””多行注釋”””時優先展示多行注釋，就不展示頂部的#號的注釋了

 

第三部分：function，模塊下的def方法，不是class中的方法

1.function上面有#注釋時，展示#號的注釋

2.function下有”””多行注釋”””時優先展示多行注釋，就不展示頂部的#號的注釋了

 

第四部分：data，模塊下直接定義的變量，不是function或class的變量

 

示例代碼：

"""
@author 每天1990
@desc 本模塊是一個測試文件，用來說明pydoc的讀取內容
@date 2017/4/13
說明：
classes:testclass()，具有function1()和function2()兩個方法

function：test1()，test2()，test3()

Data：a，b
"""

#注釋放在方法名前，使用#號注釋
def test1(a):
    print("注釋放在方法名前")

#注釋放在方法名前，使用#號注釋
def test2():
    """
    注釋放在方法內的第一行，既有#號又有多行注釋時，優先展示多行注釋
    """
    print("既有#號又有多行注釋時，優先展示多行注釋 ")

def test3():
    #在方法第一行內使用#注釋
    print("在方法內使用#號注釋，不生效")

class testclass():
    """
    注釋生效順序與方法一致，優先展示類下的多行注釋，如果沒有才展示類上面的#號注釋
    類下的方法的注釋不會展示出來
    """
    def function1(self):#類下方法的注釋不會展示
        print("類下的第一個方法")
    def function2(self,a):
        print("類下的第二個參數，包含a參數")


a=1#變量的注釋不會展示出來
b=2

三、注釋方法

通過上面的文檔說明，我們可以合理的注釋，有助於了解工程結構

python的注釋方法有兩種：

1.單行注釋：使用#號進行注釋

#單行注釋

 

2.多行注釋：使用三個雙引號或單引號來注釋多行內容

'''
單引號進行多行注釋

'''

 

"""

雙引號進行多行注釋

"""

pydoc注釋展示策略：

在functions和classes前面加#注釋，或者在function和class第一行內加三個單引號或三個雙引號進行注釋

如果有三個引號的注釋方法，會優先使用三個點的注釋，其次才展示#號的注釋

 

注意：如果在方法或class定義后第一行使用#注釋是拉取不到注釋的

 

例子1：class前有#號注釋，class內有多行注釋，pydoc會優先展示三個點內的注釋

 

例子2：方法內使用#號注釋，pydoc不會顯示注釋內容（class同理）

 

例子3：方法或class沒有多行注釋，只在方法外有#號注釋時，會展示定義前的#號內的內容

 

例子4：模塊頂部的內容，優先展示多行注釋中的內容

 

 

 

 

 

 

 

 

 

 

 

轉載自：https://www.cnblogs.com/meitian/p/6704488.html