python pydoc-文档生成工具(汇总tcy)

pydoc-文档生成工具 2018/9/8

------------------------------------------------------------------------------

1.1.用途：

是python自带的一个文档生成工具，使用pydoc可以很方便的查看类和方法结构

python中pydoc模块可以从python代码中获取docstring，然后生成帮助信息。

主要用于从python模块中自动生成文档，这些文档可以基于文本呈现的、也可以生成WEB 页面的，还可以在服务器上以浏览器的方式呈现！

pydoc - Python文档工具

-------------------------------------------------------------------------------

1.2.方法：

pydoc <name> ...

显示关于某事的文本文档。 <name>可以是a的名称 Python关键字，主题，功能，模块或包，或点缀引用模块或模块中的类或函数包。

如果<name>包含'\\'，则将其用作a的路径 Python源文件到文档。如果名称是'关键字'，'主题'，或“模块”，显示这些内容的列表。

pydoc -k <keyword>

在所有可用模块的概要行中搜索关键字。

pydoc -n <hostname>

使用给定的主机名启动HTTP服务器（默认值：localhost）。

pydoc -p <port>

在本地计算机上的给定端口上启动HTTP服务器。港口

数字0可用于获取任意未使用的端口。

pydoc -b

在任意未使用的端口上启动HTTP服务器并打开Web浏览器

以交互方式浏览文档。此选项可用于与-n和/或-p组合。

pydoc -w <name> ...

将模块的HTML文档写入当前文件目录。如果<name>包含'\\'，则将其视为文件名;

如果它命名一个目录，为所有内容编写文档。

------------------------------------------------------------------------------

2.查看文档方法

2.1.启用服务器查看

方法1：启动本地服务，在web上查看文档

C:\Users\Administrator>python -m pydoc -p 1234

Server ready at http://localhost:1234/

Server commands: [b]rowser, [q]uit

server>

方法2：通过http://localhost:1234来访问查看文档

说明：

1、-p指定启动服务的端口号，可以随意指定不冲突端口号

2、只有在自建的工程根目录下使用该命令，才能看到当前工程下所有的内容，否则只能看到python环境变量下的模块内容

3、如果本地只有一个python，可以直接使用【pydoc -p 端口号】启动，但因为我本地有python2和python3，所以指定了用python3

-------------------------------------------------------------------------------

2.2.直接查看*.py文件内容

步骤1：新建文件c:\python37\lib\test_pydoc.py

见下文：实例代码

步骤2：进入testpydoc.py所在目录

C:\Users\Administrator>cd c:\python37\lib

步骤3：运行

C:\python37\lib\>python -m pydoc test_pydoc

步骤4：显示

见下文：显示”直接查看test_pydoc.py文件内容 ”

c:\python37\Lib>

-------------------------------------------------------------------------------

2.3.生成html说明文档

运行：

c:\python37\Lib>python -m pydoc -w test_pydoc

显示：

wrote test_pydoc.html

说明：在c:\python37\Lib\test_pydoc.html文档已经生成；和上面的查看内容相同；

默认将当前目录下的testpydoc生成一个叫做testpydoc.html的文档，如果是目录直接【python3 -m pydoc -w 目录名】生成文档

如果是将整个目录生成这种格式，不建议用这种方式，因为如果他展示目录下的子文件的说明时，会去子目录下找对应.html文件，如果文件不存在，就会404

-------------------------------------------------------------------------------

2.4.-k查找模块

用途：

py通过-k查找模块，会在当前工程目录以及python环境变量目录下查找包含关键词的模块信息

命令：

c:\python37\Lib>python -m pydoc -k test_pydoc

显示：

test.pydoc_mod - This is a test module for test_pydoc

test.test_pydoc

test_pydoc - @filename: c:\python\lib\ test_pydoc.py

-------------------------------------------------------------------------------

3.1.html文档说明

通过查看文档的方法，我们可以看到在html的文档主要分成四部分：py文件的顶部注释、Classes、Functions、Data

第一部分：模块的文档说明，展示模块顶部的多行注释

注释内如果包含了模块文件内的class名，或方法名()，则显示蓝色，且可以点击跳转到对应说明位置

第二部分：classes，展示class以及class下的function

1.只能展示class下的注释，不会展示class下方法的注释

2.class上面有#注释时，展示#号的注释

3.class下有”””多行注释”””时优先展示多行注释，就不展示顶部的#号的注释了

第三部分：function，模块下的def方法，不是class中的方法

1.function上面有#注释时，展示#号的注释

2.function下有”””多行注释”””时优先展示多行注释，不展示顶部#号的注释了

第四部分：data，模块下直接定义的变量，不是function或class的变量

------------------------------------------------------------------------------

3.2.注释方法

python注释方法：

单行注释：使用#号进行注释

多行注释：使用三个双引号或单引号来注释多行内容

pydoc注释展示策略：

在functions和classes前面加#注释，或者在function和class第一行内加三个单引号或三个双引号进行注释

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

注意：如果在方法或class定义后第一行使用#注释是拉取不到注释的

----------------------------------------------------------------------------

4.1.示例代码：

"""
@filename: c:\python\lib\ test_pydoc.py
@author     tcy1
@desc       本模块是一个测试文件说明pydoc读取内容
@date        2018/9/13
说明：
    classes: MyClass()
    Method: class_fun1();class_fun2();class_fun3()
    function: tun1()，fun2()，fun3()
    Data：a，b , c1, g1
"""
#filename: c:\python\lib\ test_pydoc.py
#模块开头单行注释和多行注释只能选一个最上面的显示

__author__ = "tcy"

#fun1()上的注释：注释放在方法名前用'#'号注释
def fun1(a):
a=100
print("注释放在方法名前",a)

#fun2()上的注释：由于下面有多行注释，本行不会被显示
def fun2():
    """
    fun2()多行注释；优先显示；
    """
    print("既有'#'号又有多行注释时，优先展示多行注释 ")

def fun3():
#在方法第一行内使用'#'注释不生效
print("在方法内使用#号注释，不生效")

#Myclass 类上注释，由于有多行注释，本行不会显示
class MyClass():
    """
    1.注释生效顺序与方法一致，优先展示类下的多行注释
    2.如没多行注释，显示类上面的 ‘#’ 号注释

    """
    g1=200#变量注释不会显示

    def __init__(self,x,y):
        self.x=x             #变量注释不会显示
        self.y=y            #变量注释不会显示

#class_fun1 ()单行注释不显示
    def class_fun1(self):#类下方法的注释不会展示
        """ class_fun1 ()多行注释"""
        print("类下的第一个方法")

# class_fun12()单行注释
def class_fun2(self,a):
print("类下的第二个参数，包含a参数")

def class_fun3(self):
print("类方法无注释")

a=1 #变量注释不会显示
b=2 #变量注释不会显示
c1=MyClass(1000,-2000) #变量注释不会显示

-------------------------------------------------------------------------------

4.2.显示”直接查看test_pydoc.py文件内容 ”

c:\python37\Lib>python -m pydoc test_pydoc

Help on module test_pydoc:

NAME

test_pydoc

DESCRIPTION

@filename: c:\python\lib\ test_pydoc.py

@author tcy1

@desc 本模块是一个测试文件说明pydoc读取内容

@date 2018/9/13

说明：

classes: MyClass()

Method: class_fun1();class_fun2();class_fun3()

function: tun1()，fun2()，fun3()

Data：a，b , c1, g1

CLASSES

builtins.object

MyClass

class MyClass(builtins.object)

| MyClass(x, y)

| 1.注释生效顺序与方法一致，优先展示类下的多行注释

| 2.如没多行注释，显示类上面的 ‘#’ 号注释

| Methods defined here:

| __init__(self, x, y)

| Initialize self. See help(type(self)) for accurate signature.

| class_fun1(self)

| class_fun1 ()多行注释

| class_fun2(self, a)

| # class_fun12()单行注释

| class_fun3(self)

| ----------------------------------------------------------------------

| Data descriptors defined here:

| __dict__

| dictionary for instance variables (if defined)

| __weakref__

| list of weak references to the object (if defined)

| ----------------------------------------------------------------------

| Data and other attributes defined here:

| g1 = 200

FUNCTIONS

fun1(a)

#fun1()上的注释：注释放在方法名前用'#'号注释

fun2()

fun2()多行注释；优先显示；

fun3()

DATA

a = 1

b = 2

c1 = <test_pydoc.MyClass object>

AUTHOR

tcy

FILE

c:\python37\lib\test_pydoc.py

-------------------------------------------------------------------------------

python pydoc-文档生成工具(汇总tcy)相关推荐

sphinx：基于 Python 的文档生成工具
sphinx:基于 Python 的文档生成工具 Motivation 对于软件开发来说,文档是软件可维护性的重要保障.sphinx 是一款文档生成工具,以 restructuredText 为标记语 ...
python doc_Python文档生成工具pydoc使用介绍
在Python中有很多很好的工具来生成字符串文档(docstring),比如说: epydoc.doxygen.sphinx,但始终觉得pydoc还是不错的工具,用法非常简单,功能也算不错,本文主要介 ...
关于深度学习框架Hamaa与Python API文档生成工具Sophon
五月两场 | NVIDIA DLI 深度学习入门课程 5月19日/5月26日一天密集式学习快速带你入门阅读全文> 正文共1988个字,预计阅读时间12分钟. 前言最近三个月我主要花时间在造 ...
python文档生成_python文档生成工具：pydoc、sphinx；django如何使用sphinx？
文档生成工具: 自带的pydoc,比较差建议使用sphinx 安装: pip install sphinx 安装主题: 由各种主题,我选择常用的sphinx_rtd_theme pip instal ...
Apiggs —— 非侵入性的 RestDoc 文档生成工具
程序员一直以来都有一个烦恼,只想写代码,不想写文档.代码就表达了我的思想和灵魂. Python提出了一个方案,叫docstring,来试图解决这个问题.即编写代码,同时也能写出文档,保持代码和文档的一 ...
Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...
一款常用文档生成工具：Doxygen
关注+星标公众号,不错过精彩内容来源 | 简书编排 | strongerHuang 程序员的很多文档,特别是有代码的文档,绝大部分都是由一款文档生成工具[Doxygen]生成. 什么是Doxyge ...
mysql 文档生成器_最好用的数据库文档生成工具
一前言本文介绍一些比较流行的数据库文档生成工具,什么是数据库文档? 其实在工作中进行项目交付的时候经常用到:简单来说数据库文档就是对整个数据库设计说明的文档,比如使用了哪个数据库,每张表的字段,类 ...
.NET平台开源项目速览(4).NET文档生成工具ADB及使用
.NET平台开源项目速览(4).NET文档生成工具ADB及使用原文:.NET平台开源项目速览(4).NET文档生成工具ADB及使用很久以前就使用ADB这个工具来生成项目的帮助文档.功能强大,在学习 ...

python pydoc-文档生成工具(汇总tcy)

python pydoc-文档生成工具(汇总tcy)相关推荐

最新文章

热门文章