Python编程：使用pydoc生成文档注释

pydoc是python自带的一个文档生成工具，可以提取注释

如果有三个引号的注释方法，会优先使用三个点的注释，其次才展示#号的注释

示例使用的代码pydoc_demo.py，包含一个函数，一个类

# -*- coding: utf-8 -*-

# @Date    : 2018-10-30
# @Author  : Peng Shiyu

"""
这个文档注释pydoc的示例
"""

# 函数名上方的文字
def func():
    """
    函数名下方的注释
    @return: None
    """
    print("hello")


# 类名上方的文字
class Demo():
    """
    类名下方的文字
    """

    # 类中方法上方的文字
    def hello(self):
        """
        类中方法下方的文字
        @return: None
        """
        print("hello")

生成文档

$ pydoc pydoc_demo > doc.md

将文档重定向到doc.md文件中，内容如下

Help on module pydoc_demo:

NAME
    pydoc_demo - 这个文档注释pydoc的示例

CLASSES
    builtins.object
        Demo
    
    class Demo(builtins.object)
     |  类名下方的文字
     |  
     |  Methods defined here:
     |  
     |  hello(self)
     |      类中方法下方的文字
     |      @return: None
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    func()
        函数名下方的注释
        @return: None

FILE
   /demo/pydoc_demo.py

生成html

$ pydoc -w pydoc_demo

出现新文件pydoc_demo.html

颜色看上去很鲜艳

参考
pydoc用法