幫助手冊

回憶上次內(nèi)容

• 上次了解了注釋

• 注釋是為了讓程序更可讀

• 注釋不會影響程序運(yùn)行速度

• 注釋分為兩種

• 三個(gè)"

• 三個(gè)'

• 以#開頭

• 不能是字符串當(dāng)中的#

• 單行的

• 多行的

• 多行注釋還有什么特殊功能么？??

增加描述說明

• 原始文檔如下圖

• 插入三引號注釋

• 如下圖所示

• 準(zhǔn)備插入下面三項(xiàng)的注釋

• date 編寫日期

• description 描述信息

• author 作者

填寫注釋

• 將光標(biāo)放在

• 第4行第1列

• :r !date

• 將外部命令date輸出的結(jié)果

• 輸出到當(dāng)前文件緩存中

• 可以在shell中執(zhí)行外部命令date

• 是外部shell中可以執(zhí)行的命令

• 可以得到當(dāng)前日期時(shí)間

• date

• !date

• r !date

繼續(xù)完成

• 填寫完成注釋

• 注意

• 已經(jīng)設(shè)置了 編碼格式

• :wq

• 寫完之后

• 保存并退出回到shell

• 可以在命令行中

• 查看到 main.py 的幫助手冊嗎？

刷新幫助手冊

• python3 -m pydoc main

• -m pydoc 使用pydoc模塊

• pydoc 就是 python的 document 文檔

• 整體就可以得到

• main.py模塊的幫助文檔手冊

• 會先運(yùn)行這個(gè)main.py

查看幫助

• 然后會顯示main模塊的幫助

• 這很眼熟啊

• 可以到游樂場里面

• 首先 import main

• 然后 help(main)

生成幫助手冊

• 在當(dāng)前路徑，進(jìn)入游樂場之后

• import main

• help(main)

• 一樣可以看到相關(guān)的文檔

• 可以生成幫助網(wǎng)頁嗎？

• 就像官方的那種幫助一樣

• 官方的幫助什么樣子？

python3 在線

• python3 本身有在線的文檔

• 在http://docs.python.org

• 可以生成我代碼的文檔嗎？

生成網(wǎng)頁

• python3 -m pydoc -w main

• 幫助網(wǎng)頁 main.html

• 對于 main.py 生成

• 注意最后一句

• wrote main.html

• 寫下了一個(gè)新文件

• 這個(gè)文件main.html

• 就是main.py的幫助文件

• 就生成在當(dāng)前的 test 文件夾

打開幫助網(wǎng)頁

• 然后用火狐打開這個(gè)網(wǎng)頁文件

• firefox main.html

• 右上角是兩個(gè)鏈接

• 當(dāng)前文件夾索引

• 當(dāng)前 html 對應(yīng)的 py 文件

• 下面是 main 里面的內(nèi)容

• 相關(guān)的三引號描述

• 再下面是三個(gè)鏈接

• 是 main.py 引入的三個(gè) module

• 目前這三個(gè)模塊的鏈接都無法打開

• 因?yàn)槎歼€沒有生成

更新其他模塊幫助文件

• get_fruits 本來就有三引號注釋

• python3 -m pydoc -w get_fruits

• 生成了網(wǎng)頁

• 再次用firefox 打開 main.html

網(wǎng)頁細(xì)節(jié)

• 點(diǎn)擊get_fruits

• 跳轉(zhuǎn)到get_fruits模塊的幫助文檔

注意文檔

• 紅框中

• 只提到了 apple

• 沒有提到banana

• 只有最開頭的三引號注釋

• 才被寫入模塊幫助

• 后面再有三引號注釋

• 只是注釋

• 不會被寫到文檔中

• 下面的三引號注釋被忽略

修改模塊注釋

• 修改 get_fruits.py

• 頭部三引號注釋

• 保存并寫幫助網(wǎng)頁

• :w|!python3 -m pydoc -w get_fruits

• 使用火狐打開get_fruits.html

• :!firefox get_fruits.html

• 模塊幫助文檔更新了

• 把文檔寫在代碼里好嗎？

代碼即文檔

• CodeAsDocumentation

• 讓源代碼更容易閱讀和理解

• 盡量減少維護(hù)或擴(kuò)展遺留系統(tǒng)所需的工作量

• 減少系統(tǒng)的用戶和開發(fā)人員查閱二級文檔來源的需要

• 通過自成一體的知識表征促進(jìn)自動(dòng)化

這很敏捷

總結(jié)

• 這次了解了 幫助文檔的 生成

• 開頭的三引號注釋 可以生成 幫助文檔

• 文檔 可以寫成網(wǎng)頁

• python3 本身

• 也有 在線的幫助手冊

• 目前的程序

• 提高了 可讀性

• 有什么方法

• 可以讓程序 更可讀么？??

• 下次再說！??

• 藍(lán)橋->https://www.lanqiao.cn/courses/3584

• github->https://github.com/overmind1980/oeasy-python-tutorial

• gitee->https://gitee.com/overmind1980/oeasypython