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

比眉伴天荒 2022-10-07 12:54 336阅读 0赞

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

关于html的样式是下面这种形式。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70]  
对于常见的类似下面这种样式的，是利用sphinx自动生成。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 1]  
先介绍先如何利用pydoc自动生成说明文档，后面会再写篇博客记录下Sphinx自动生成文档的博客。

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

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

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

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

命令【python -m pydoc -p 1234】

注意：

*  \-p 指定启动的服务的端口号，可以随意指定不冲突的端口号
 *  只有在自建的工程根目录下使用该命令，才能看到当前工程下所有的内容，否则只能看到python环境变量下的模块内容  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 2]  
    这种方式没办法保存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的文件如下所示，当去点击某个子包的内容，或者某个文件的内容时出现无法访问您的文件该文件可能已被移至别处、修改或删除，这个问题。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 3]  
主要原因：没有生成相关内容的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]  
[可能会遇到的一些问题的解决][Link 1]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70]: /images/20221005/ec6fd5740c434ae2a32ec77a0bcd2c93.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 1]: /images/20221005/101cea9a6ea14e90895245e78b314b98.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 2]: /images/20221005/0bba618e2b674fb6a0b6d369dd6a7b2d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 3]: /images/20221005/06b245bc8da442a781f229111277ff83.png
[pydoc]: https://docs.python.org/3/library/pydoc.html?highlight=pydoc
[Link 1]: https://stackoverflow.com/questions/13040646/how-do-i-create-documentation-with-pydoc