pydoc是python自带的一个文档生成工具，pydoc可以直接生成html、md的说明文档，也可以启动本地服务，在web上查看文档。

关于html的样式是下面这种形式。

对于常见的类似下面这种样式的，是利用sphinx自动生成。

先介绍先如何利用pydoc自动生成说明文档，后面会再写篇博客记录下Sphinx自动生成文档的博客。

下面首先介绍下pydoc的简单常用的一些命令，然后拿一个复杂的例子，记录下遇到的一些问题的解决方法。

如何利用pydoc自动生成说明文档

如果只想生成html的说明文档，直接看4

1.启动本地服务，查看文档

命令【python -m pydoc -p 1234】

注意：

-p 指定启动的服务的端口号，可以随意指定不冲突的端口号
只有在自建的工程根目录下使用该命令，才能看到当前工程下所有的内容，否则只能看到python环境变量下的模块内容

这种方式没办法保存html，只能去查看而已。

2.直接查看某个py文件的内容

例如对于testpydoc.py文件，查看这个文件中的注释内容，使用如下命令。

python -m pydoc testpydoc

这种只可以在命令行下查看

3.生成md文档

例如，将test.py生成md文档

pydoc test > doc.md

会将文档重定向到doc.md文件中。

4.生成html说明文档

如下对testpydoc.py这个文件生成html的说明文档

python -m pydoc -w testpydoc

上面命令主要就是为 pydoc 模块额外指定了 -w 选项，该选项代表 write，表明输出 HTML 文档。

注释展示策略

会优先展示类、方法中的""" ----- """中的内容，不会对单行注释进行解释，如果某个类或者方法内没有这部分内容，会查看该类、方法外的前一行是否有单行注释，如果有单行注释，会显示单行注释。

常见的问题

1.No Python documentation found for

No Python documentation found for …
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

主要的原因是，未进入到文件所在目录，出现提示找不到文件。
解决方法：需要cd到对应目录下

2.pydoc无法访问您的文件该文件可能已被移至别处、修改或删除。

当我们对某个package或目录自动生成文档时，只生成了一个html的文件如下所示，当去点击某个子包的内容，或者某个文件的内容时出现无法访问您的文件该文件可能已被移至别处、修改或删除，这个问题。

主要原因：没有生成相关内容的html，只生成了一个html
解决方法：对某个package使用pydoc -w时，需要在包前面加一个‘\’，然后就会生成这个包下面的字包以及其他文件的html，然后再点击某个文件就不会出现这个问题了

3.-w后面必须跟文件名，不能是路径

如果我们想要生成某个文件的html说明文档，我们必须cd到当前的目录下，不可以使用路径名。

4.note

遇到红以后，不要慌，好好翻译一些是什么情况，然后再找解决办法，有的红，是警告不影响结果。

参考链接：
https://www.cnblogs.com/meitian/p/6704488.html
https://www.cnblogs.com/niaocaizhou/p/12072812.html
pydoc官方内容
可能会遇到的一些问题的解决

pydoc自动生成说明文档及常见问题解决相关推荐

Eclipse用法和技巧五：生成说明文档2
上面一篇文章里面我们介绍了一种生成可以被JDK提取到,生成JavaDoc的添加注释方法.下面再补充一种生成这种注释的方法,上图: 步骤一:光标移动到需要添加注释的语句旁边,快捷键:shift + al ...
Eclipse用法和技巧四：生成说明文档1
写代码经常要添加注释的,java代码的注释也可以分为两种.单行注释以"//"作为开头就可以.段落注释在第一行开头添加"/*",在最后一行结尾添加"*/ ...
【java】将自己写的类生成说明文档的方法
使用工具: jdk中的javadoc 实现步骤: 1.将java文件放到一个目录之下 2.进入doc(win+R,输入cmd) 3.通过cd指令进入存放java文件的文件夹 4.编译java文件代码 ...
.net core webapi 通过swagger生成说明文档
1.通过nuget安装 Swashbuckle.AspNetCore 2.startup.cs=>ConfigureServices,注册swagger 3.configure中添加: app. ...
读取excel日期 c++_实例9：用Python自动生成Excel档每日出货清单
公司研发部门每年都需要向税务局提交一份出货清单,以申报研发费用.要求按日期来汇总,每日只要有出货,就需要一份出货单.出货总表包含数百条出货记录.假设一年有200天都出过货,那按照常规的方法,需要从总表 ...
python生成excel模板_实例9：用Python自动生成Excel档每日出货清单
公司研发部门每年都需要向税务局提交一份出货清单,以申报研发费用.要求按日期来汇总,每日只要有出货,就需要一份出货单.出货总表包含数百条出货记录.假设一年有200天都出过货,那按照常规的方法,需要从总表 ...
Doxygen —— 快来为你的代码自动生成一份专属说明文档
简介 Doxygen是一个能从带注释的源码中自动生成说明文档的标准工具,它支持众多流行的编程语言,包括C/C++.C#, PHP, Java, Python, IDL 等 Doxygen能够从以下三个 ...
【Doxygen】为项目生成一个炫酷的说明文档
[Doxygen]为项目生成一个炫酷的说明文档目录 [Doxygen]为项目生成一个炫酷的说明文档 1 Doxygen简介 2 安装 Doxygen 3 基本使用方式 3.1 从命令行生成 3.1. ...
【原创】SQlServer数据库生成简单的说明文档小工具(附源码)
这是一款简单的数据库文档生成工具,主要实现了SQlServer生成说明文档的小工具,目前不够完善,主要可以把数据库的表以及表的详细字段信息,导出到 Word中,可以方便开发人员了解数据库的信息或写技术 ...

pydoc自动生成说明文档及常见问题解决