python pydoc-文件生成工具(彙總tcy)
pydoc-文件生成工具 2018/9/8
------------------------------------------------------------------------------
1.1.用途：
是python自帶的一個文件生成工具，使用pydoc可以很方便的檢視類和方法結構
python中pydoc模組可以從python程式碼中獲取docstring，然後生成幫助資訊。
主要用於從python模組中自動生成文件，這些文件可以基於文字呈現的、也可以生成WEB 頁面的，還可以在伺服器上以瀏覽器的方式呈現！
pydoc - Python文件工具
-------------------------------------------------------------------------------
1.2.方法：
pydoc <name> ...
顯示關於某事的文字文件。 <name>可以是a的名稱 Python關鍵字，主題，功能，模組或包，或點綴引用模組或模組中的類或函式包。
如果<name>包含'\\'，則將其用作a的路徑 Python原始檔到文件。如果名稱是'關鍵字'，'主題'，或“模組”，顯示這些內容的列表。
pydoc -k <keyword>
在所有可用模組的概要行中搜索關鍵字。
pydoc -n <hostname>
使用給定的主機名啟動HTTP伺服器（預設值：localhost）。
pydoc -p <port>
在本地計算機上的給定埠上啟動HTTP伺服器。港口
數字0可用於獲取任意未使用的埠。
pydoc -b
在任意未使用的埠上啟動HTTP伺服器並開啟Web瀏覽器
以互動方式瀏覽文件。此選項可用於與-n和/或-p組合。
pydoc -w <name> ...
將模組的HTML文件寫入當前檔案目錄。如果<name>包含'\\'，則將其視為檔名;
如果它命名一個目錄，為所有內容編寫文件。
------------------------------------------------------------------------------
2.檢視文件方法
2.1.啟用伺服器檢視
方法1：啟動本地服務，在web上檢視文件
C:\Users\Administrator>python -m pydoc -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>
方法2：通過http://localhost:1234來訪問檢視文件
說明：
1、-p指定啟動服務的埠號，可以隨意指定不衝突埠號
2、只有在自建的工程根目錄下使用該命令，才能看到當前工程下所有的內容，否則只能看到python環境變數下的模組內容
3、如果本地只有一個python，可以直接使用【pydoc -p 埠號】啟動，但因為我本地有python2和python3，所以指定了用python3
-------------------------------------------------------------------------------
2.2.直接檢視*.py檔案內容
步驟1：新建檔案c:\python37\lib\test_pydoc.py
見下文：例項程式碼
步驟2：進入testpydoc.py所在目錄
C:\Users\Administrator>cd c:\python37\lib
步驟3：執行
C:\python37\lib\>python -m pydoc test_pydoc
步驟4：顯示
見下文：顯示”直接檢視test_pydoc.py檔案內容 ”
c:\python37\Lib>
-------------------------------------------------------------------------------
2.3.生成html說明文件
執行：
c:\python37\Lib>python -m pydoc -w test_pydoc
顯示：
wrote test_pydoc.html
說明：在c:\python37\Lib\test_pydoc.html文件已經生成；和上面的檢視內容相同；
預設將當前目錄下的testpydoc生成一個叫做testpydoc.html的文件，如果是目錄直接【python3 -m pydoc -w 目錄名】生成文件
如果是將整個目錄生成這種格式，不建議用這種方式，因為如果他展示目錄下的子檔案的說明時，會去子目錄下找對應.html檔案，如果檔案不存在，就會404
-------------------------------------------------------------------------------
2.4.-k查詢模組
用途：
py通過-k查詢模組，會在當前工程目錄以及python環境變數目錄下查詢包含關鍵詞的模組資訊
命令：
c:\python37\Lib>python -m pydoc -k test_pydoc
顯示：
test.pydoc_mod - This is a test module for test_pydoc
test.test_pydoc
test_pydoc - @filename: c:\python\lib\ test_pydoc.py
-------------------------------------------------------------------------------
3.1.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的變數
------------------------------------------------------------------------------
3.2.註釋方法
python註釋方法：
單行註釋：使用#號進行註釋
多行註釋：使用三個雙引號或單引號來註釋多行內容
pydoc註釋展示策略：
在functions和classes前面加#註釋，或者在function和class第一行內加三個單引號或三個雙引號進行註釋
如果有三個引號的註釋方法，會優先使用三個點的註釋，其次才展示#號的註釋
注意：如果在方法或class定義後第一行使用#註釋是拉取不到註釋的
----------------------------------------------------------------------------
4.1.示例程式碼：
"""
@filename: c:\python\lib\ test_pydoc.py
@author tcy1
@desc 本模組是一個測試檔案說明pydoc讀取內容
@date 2018/9/13
說明：
classes: MyClass()
Method: class_fun1();class_fun2();class_fun3()
function: tun1()，fun2()，fun3()
Data：a，b , c1, g1
"""
#filename: c:\python\lib\ test_pydoc.py
#模組開頭單行註釋和多行註釋只能選一個最上面的顯示
__author__ = "tcy"
#fun1()上的註釋：註釋放在方法名前用'#'號註釋
def fun1(a):
a=100
print("註釋放在方法名前",a)
#fun2()上的註釋：由於下面有多行註釋，本行不會被顯示
def fun2():
"""
fun2()多行註釋；優先顯示；
"""
print("既有'#'號又有多行註釋時，優先展示多行註釋 ")
def fun3():
#在方法第一行內使用'#'註釋不生效
print("在方法內使用#號註釋，不生效")
#Myclass 類上註釋，由於有多行註釋，本行不會顯示
class MyClass():
"""
1.註釋生效順序與方法一致，優先展示類下的多行註釋
2.如沒多行註釋，顯示類上面的 ‘#’ 號註釋
"""
g1=200#變數註釋不會顯示
def __init__(self,x,y):
self.x=x #變數註釋不會顯示
self.y=y #變數註釋不會顯示
#class_fun1 ()單行註釋不顯示
def class_fun1(self):#類下方法的註釋不會展示
""" class_fun1 ()多行註釋"""
print("類下的第一個方法")
# class_fun12()單行註釋
def class_fun2(self,a):
print("類下的第二個引數，包含a引數")
def class_fun3(self):
print("類方法無註釋")
a=1 #變數註釋不會顯示
b=2 #變數註釋不會顯示
c1=MyClass(1000,-2000) #變數註釋不會顯示
-------------------------------------------------------------------------------
4.2.顯示”直接檢視test_pydoc.py檔案內容 ”
c:\python37\Lib>python -m pydoc test_pydoc
Help on module test_pydoc:
NAME
test_pydoc
DESCRIPTION
@filename: c:\python\lib\ test_pydoc.py
@author tcy1
@desc 本模組是一個測試檔案說明pydoc讀取內容
@date 2018/9/13
說明：
classes: MyClass()
Method: class_fun1();class_fun2();class_fun3()
function: tun1()，fun2()，fun3()
Data：a，b , c1, g1
CLASSES
builtins.object
MyClass
class MyClass(builtins.object)
| MyClass(x, y)
|
| 1.註釋生效順序與方法一致，優先展示類下的多行註釋
| 2.如沒多行註釋，顯示類上面的 ‘#’ 號註釋
|
| Methods defined here:
|
| __init__(self, x, y)
| Initialize self. See help(type(self)) for accurate signature.
|
| class_fun1(self)
| class_fun1 ()多行註釋
|
| class_fun2(self, a)
| # class_fun12()單行註釋
|
| class_fun3(self)
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| g1 = 200
FUNCTIONS
fun1(a)
#fun1()上的註釋：註釋放在方法名前用'#'號註釋
fun2()
fun2()多行註釋；優先顯示；
fun3()
DATA
a = 1
b = 2
c1 = <test_pydoc.MyClass object>
AUTHOR
tcy
FILE
c:\python37\lib\test_pydoc.py
-------------------------------------------------------------------------------