python文档管理

python文档说明

文档管理的作用
文档管理模块pydoc介绍
怎么使用文档管理

• 文档管理的作用

  通过在模块/类/函数中进行规范化注释，可以有效的说明模块/类/函数的功能；清晰的体现程序的结构；

• 文档管理模块pydoc.py

  文档管理模块pydoc，是python内置的一个文档管理模块。它可以实现在线实时/离线查看。模块/类/函数（内置/第三方/自有均支持）中的注释信息，同时可以将规范的注释信息生成html文件进行查看；

• 怎么实现

  模块中注释的规范
  文档管理模块实时查看
  文档管理模块生成html文件查看

  • 模块中注释的规范

     e.g
     # -*- coding: utf-8 -*-
     
     """
     @author jw
     @desc 本模块是一个测试文件，用来说明pydoc的读取内容
     @date 2017/4/13
     """
     
     #测试变量
     data=1
     
     class Test():
         """
         测试类
         """
     
         def test_c(s):
             """
             测试函数
             """
             pass
     
     def test():
         """
         测试函数
         """
         pass
         
  以上就是相对标准的注释规范，注释一般由三部分构成模块的注释，类的注释，函数的注释；以上注释在编译后，可使用pydoc进行查看，如下图，第一个区域是顶部注释；第二个区域是类注释，其中会包含类函数，第三个区域是模块函数注释；最后为模块定义的变量；

  • _查看效果如下_：

  

  • 实时查看模块说明文档

  实时查看可使用pydoc的help方法，注意非内置模块，使用前，需要先导入模块

  

  • 离线生成html查看模块文档

  生成全局html文档命令：python  -m pydoc -p *** #在通过loaclhost:****的方式访问查看
  查看特定的对象 python -m pydoc -w test/test.Test #生成特定对象的html文件
  查找特定对象的文档 python -m pydoc -k test

PS: 上方的"""注释"""称为文档字符串，可通过对象的__doc__方法来进行查看，如Test.__doc__;