python pydoc生成API文档的实现

 更新时间:2023年12月08日 10:16:31   作者:知识的宝藏  
pydoc 模块会根据 Python 模块来自动生成文档,本文主要介绍了python pydoc生成API文档的实现,具有一定的参考价值,感兴趣的可以了解一下

pydoc是python内置的一个文档生成模块。

pydoc 模块会根据 Python 模块来自动生成文档。 生成的文档可在控制台中显示为文本页面,提供给 Web 浏览器访问或者保存为 HTML 文件。

对于模块、类、函数和方法,显示的文档内容取自文档字符串(即 __doc__ 属性),并会递归地从其带文档的成员中获取。 如果没有文档字符串,pydoc 会尝试从类、函数或方法定义上方,或是模块顶部的注释行段落获取 (参见 inspect.getcomments()).

内置函数 help() 会发起调用交互式解释器的在线帮助系统,该系统使用 pydoc 在终端上生成文本形式的文档内容。 同样的文本文档也可以在 Python 解释器以外通过在操作系统的命令提示符下以脚本方式运行 pydoc 来查看。 例如,运行

python -m pydoc sys

输出如下:

Help on built-in module sys:

NAME
    sys

MODULE REFERENCE
    https://docs.python.org/3.11/library/sys.html
-- More  --

在终端提示符下将通过 sys 模块显示文档内容,其样式类似于 Unix man 命令所显示的指南页面。 pydoc 的参数可以为函数、模块、包,或带点号的对模块中的类、方法或函数以及包中的模块的引用。 如果传给 pydoc 的参数像是一个路径(即包含所在操作系统的路径分隔符,例如 Unix 的正斜杠),并且其指向一个现有的 Python 源文件,则会为该文件生成文档内容。

备注:为了找到对象及其文档内容,pydoc 会导入文档所在的模块。 因此,任何模块层级的代码都将被执行。 请使用 if __name__ == '__main__': 语句来确保一个文件的特定代码仅在作为脚本被发起调用时执行而不是在被导入时执行。

当打印输出到控制台时,pydoc 会尝试对输出进行分页以方便阅读。 如果设置了 PAGER 环境变量,pydoc 将使用该变量值作为分页程序。

在参数前指定 -w 旗标将把 HTML 文档写入到当前目录下的一个文件中,而不是在控制台中显示文本。

在参数前指定 -k 旗标将在全部可用模块的提要行中搜索参数所给定的关键字,具体方式同样类似于 Unix man 命令。 模块的提要行就是其文档字符串的第一行。

你还可以使用 pydoc 在本机上启动一个 HTTP 服务器并向来访的 Web 浏览器展示文档。 python -m pydoc -p 1234 将在 1234 端口上启动 HTTP 服务器,允许在你所用的 Web 浏览器上通过 http://localhost:1234/ 来浏览文档。 指定 0 作为端口号将任意选择一个未使用的端口。

python -m pydoc -n <hostname> 将启动在给定主机名上监听的服务器。 默认的主机名为 'localhost' 但是如果你希望能从其他机器上搜索该服务器,你可能会想要改变服务器所响应的主机名。 在开发阶段此特性会特别有用,如果你想要在一个容器中运行 pydoc 的话。

python -m pydoc -b 将启动服务器并额外打开一个 Web 浏览器访问模块索引页。 所发布的每个页面顶端都带有导航栏,你可以点击 Get 来获取特定条目的帮助信息,点击 Search 在所有模块的摘要行中搜索某个关键词,或点击 Module index, Topics 和 Keywords 前往相应的页面。

在本地浏览器打开生成的api文档:

python -m pydoc -p 1234 -b

生成后会在本地启动一个web服务器:

(venv) PS H:\测试\requests-main> python -m pydoc -p 1234 -b
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server> 

当 pydoc 生成文档内容时,它会使用当前环境和路径来定位模块。 因此,发起调用 pydoc spam 得到的文档版本会与你启动 Python 解释器并输入 import spam 时得到的模块版本完全相同。

核心模块的模块文档位置对应于 https://docs.python.org/X.Y/library/ 其中 X 和 Y 是 Python 解释器的主要版本号和小版本号。 这可通过设置 PYTHONDOCS 环境变量来重载为指向不同的 URL 或包含 Library Reference Manual 页面的本地目录。

到此这篇关于python pydoc生成API文档的实现的文章就介绍到这了,更多相关python pydoc生成API文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

您可能感兴趣的文章:

相关文章

  • 关于python中map函数的使用

    关于python中map函数的使用

    这篇文章主要介绍了关于python中map函数的使用,map函数也是python中的一个内置函数,用法同之前讲过的filter函数类似,需要的朋友可以参考下
    2023-04-04
  • pytorch构建多模型实例

    pytorch构建多模型实例

    今天小编就为大家分享一篇pytorch构建多模型实例,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧
    2020-01-01
  • 10个简单但很有用的Python装饰器分享

    10个简单但很有用的Python装饰器分享

    装饰器(Decorators)是Python中一种强大而灵活的功能,用于修改或增强函数或类的行为,本文为大家整理了10个简单但很有用的Python装饰器,希望对大家有所帮助
    2023-08-08
  • Python Pygame实战之趣味篮球游戏的实现

    Python Pygame实战之趣味篮球游戏的实现

    这篇文章主要为大家分享了一个基于Python和Pygame实现的一个趣味篮球游戏,文中的示例代码讲解详细,对我们学习Python有一定帮助,需要的可以参考一下
    2022-04-04
  • 基于Python实现一键找出磁盘里所有猫照

    基于Python实现一键找出磁盘里所有猫照

    最近在整理我磁盘上的照片,发现不少猫照,突然觉得若能把这些猫照都挑出来,观察它们的成长轨迹也是一件不错的事情。一张一张的找实在是太费劲了,能不能自动化地找出来呢?本文将详细为大家讲讲,需要的可以参考一下
    2022-05-05
  • django搭建项目配置环境和创建表过程详解

    django搭建项目配置环境和创建表过程详解

    这篇文章主要介绍了django搭建项目配置环境和创建表过程详解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2019-07-07
  • 在Python中字典根据多项规则排序的方法

    在Python中字典根据多项规则排序的方法

    今天小编就为大家分享一篇在Python中字典根据多项规则排序的方法,具有很好的参考价值,希望对大家有所帮助。一起跟随小编过来看看吧
    2019-01-01
  • 教你用python控制安卓手机

    教你用python控制安卓手机

    不久前,我在思考如何通过向好友发送几分钟的垃圾邮件来惹恼我的朋友,而在做一些研究的过程中,我遇到了Android调试桥.在本快速指南中,我将向您展示如何使用Python与之交互以及如何创建2个快速脚本.需要的朋友可以参考下
    2021-05-05
  • Python面向对象程序设计示例小结

    Python面向对象程序设计示例小结

    这篇文章主要介绍了Python面向对象程序设计,结合实例形式总结分析了Python面向对象程序设计中比较常见的类定义、实例化、继承、私有变量等相关使用技巧与操作注意事项,需要的朋友可以参考下
    2019-01-01
  • python 如何去除字符串头尾的多余符号

    python 如何去除字符串头尾的多余符号

    这篇文章主要介绍了python 如何去除字符串头尾的多余符号,在python开发中经常会遇到这样的需求,今天小编通过实例代码给大家讲解,需要的朋友可以参考下
    2019-11-11

最新评论