[oeasy]python0069_帮助手册_pydoc_manual_document
帮助手册
回忆上次内容
上次了解了注释
注释是为了让程序更可读
注释不会影响程序运行速度
注释分为两种
三个
"三个
'以
#开头不能是字符串当中的
#单行的
多行的
多行注释还有什么特殊功能么？🤔
增加描述说明
原始文档如下图
插入三引号注释
如下图所示
准备插入下面三项的注释
date 编写日期
description 描述信息
author 作者
填写注释
将光标放在
第4行第1列
:r !date
将外部命令date输出的结果
输出到当前文件缓存中
可以在shell中执行外部命令date
是外部shell中可以执行的命令
可以得到当前日期时间
date
!date
r !date
继续完成
填写完成注释
注意
已经设置了 编码格式
:wq
写完之后
保存并退出回到shell
可以在命令行中
查看到 main.py 的帮助手册吗？
刷新帮助手册
python3 -m pydoc main-m pydoc 使用pydoc模块
pydoc 就是 python的 document 文档
整体就可以得到
main.py模块的帮助文档手册
会先运行这个main.py
查看帮助
然后会显示main模块的帮助
这很眼熟啊
可以到游乐场里面
首先 import main
然后 help(main)
生成帮助手册
在当前路径，进入游乐场之后
import main
help(main)
一样可以看到相关的文档
可以生成帮助网页吗？
就像官方的那种帮助一样
官方的帮助什么样子？
python3 在线
python3 本身有在线的文档
在http://docs.python.org
可以生成我代码的文档吗？
生成网页
python3 -m pydoc -w main帮助网页 main.html
对于 main.py 生成
注意最后一句
wrote main.html
写下了一个新文件
这个文件main.html
就是main.py的帮助文件
就生成在当前的 test 文件夹
打开帮助网页
然后用火狐打开这个网页文件
firefox main.html
右上角是两个链接
当前文件夹索引
当前 html 对应的 py 文件
下面是 main 里面的内容
相关的三引号描述
再下面是三个链接
是 main.py 引入的三个 module
目前这三个模块的链接都无法打开
因为都还没有生成
更新其他模块帮助文件
get_fruits 本来就有三引号注释
python3 -m pydoc -w get_fruits
生成了网页
再次用firefox 打开 main.html
网页细节
点击get_fruits
跳转到get_fruits模块的帮助文档
注意文档
红框中
只提到了 apple
没有提到banana
只有最开头的三引号注释
才被写入模块帮助
后面再有三引号注释
只是注释
不会被写到文档中
下面的三引号注释被忽略
修改模块注释
修改 get_fruits.py
头部三引号注释
保存并写帮助网页
:w|!python3 -m pydoc -w get_fruits使用火狐打开get_fruits.html
:!firefox get_fruits.html
模块帮助文档更新了
把文档写在代码里好吗？
代码即文档
CodeAsDocumentation
让源代码更容易阅读和理解
尽量减少维护或扩展遗留系统所需的工作量
减少系统的用户和开发人员查阅二级文档来源的需要
通过自成一体的知识表征促进自动化
这很敏捷
总结
这次了解了 帮助文档的 生成
开头的三引号注释 可以生成 帮助文档
文档 可以写成网页
python3 本身
也有 在线的帮助手册
目前的程序
提高了 可读性
有
什么方法可以让程序 更可读么？🤔
下次再说！👋
蓝桥->https://www.lanqiao.cn/courses/3584
github->https://github.com/overmind1980/oeasy-python-tutorial
gitee->https://gitee.com/overmind1980/oeasypython
