[oeasy]python049_帮助手册_pydoc_manual_document

帮助手册

回忆上次内容

• 上次了解了注释
  • 注释是为了让程序更可读
  • 注释不会影响程序运行速度
• 注释分为两种
  • 单行的
    • 以#开头
    • 不能是字符串当中的#
  • 多行的
    • 三个"
    • 三个'
• 多行注释还有什么特殊功能么？🤔

增加描述说明

#!/usr/bin/python3
#vim: set fileencoding=utf-8
'''
关于当前模块的说明
'''

• 完整的main.py如下所示
• :r !whoami
  • 可以得到当前用户名
• :r !date
  • 可以得到当前日期时间
• :w
  • 写完之后保存

• 注意 已经设置了 编码格式
• 可以在命令行中
  • 查看到 main.py 的帮助手册吗？

刷新帮助手册

• 观察帮助手册
  • python3 -m pydoc main

• 这很眼熟啊
• 可以到游乐场里面
  • 首先 import main
  • 然后 help(main)

生成帮助手册

• 一样可以看到相关的文档

• 在当前路径，进入游乐场之后
  • import main
  • help(main)
• 可以生成帮助网页吗？
  • 就像官方的那种帮助一样
• 官方的帮助什么样子？

python3 在线

• python3 本身有在线的文档
  • 在http://docs.python.org

• 可以生成我代码的文档吗？

生成网页

• python3 -m pydoc -w main
  • 对于 main.py 生成帮助网页
  • 帮助文件叫做 main.html

• 帮助文件 就生成在当前的 test 文件夹

打开帮助网页

• 然后用火狐打开这个网页文件
  • firefox main.html

• 右上角是两个链接
  • 当前文件夹索引
  • 当前 html 对应的 py 文件
• 下面是 main 里面的内容
  • 相关的三引号描述
• 再下面是三个链接
  • 是 main.py 引入的三个 module
  • 目前这三个模块的链接都无法打开
  • 因为没有生成

更新其他模块帮助文件

• 修改三个 py 文件的内容
• 其中 get_fruits 本来就有三引号注释
  • python3 -m pydoc -w get_fruits

• 只有顶端的三引号注释才被写入模块帮助
• 下面的三引号注释被忽略

修改模块注释

• 修改 get_fruits.py
  • 保存并写帮助网页
  • python3 -m pydoc -w get_fruits

• 任务完成
• 把文档写在代码里好吗？

代码即文档

• CodeAsDocumentation

• 让源代码更容易阅读和理解
• 尽量减少维护或扩展遗留系统所需的工作量
• 减少系统的用户和开发人员查阅二级文档来源的需要
• 通过自成一体的知识表征促进自动化

这很敏捷

总结

• 这次了解了 帮助文档的 生成
  • 开头的三引号注释 可以生成 帮助文档
  • 文档 可以写成网页
• python3 本身
  • 也有 在线的帮助手册
• 目前的程序
  • 提高了 可读性

• 有什么方法
  • 可以让程序 更可读么？🤔
• 下次再说！👋
• 蓝桥->https://www.lanqiao.cn/courses/3584
• github->https://github.com/overmind1980/oeasy-python-tutorial
• gitee->https://gitee.com/overmind1980/oeasypython