Python 程序有什么好的自动从注释生成文档的方法

发布网友发布时间：2022-04-30 06:00

共4个回答

懂视网时间：2022-05-06 10:30

目录索引

example1对应sphinx.rst所在目录下的example1.rst文件，example2类似。

rst如下：

.. toctree::
 :maxdepth: 2
 example1
 example2

效果如下：

二级标题1

二级标题2

引用

可以用于跨rst文档间的内容互相引用。这里以本文档内为例。

rst如下：

.. _my-reference-label:
用Sphinx编写技术文档
====================
很长的文字内容
点击回到顶部， :ref:`my-reference-label`.

效果如下：

点击回到顶部，用Sphinx编写技术文档 .

文字效果

斜体

rst如下：

*斜体*

效果如下：

斜体

粗体

rst如下：

**粗体**

效果如下：

粗体

下标

斜杠是为了空格转义，最后显示无空格。

rst如下：

H :sub:`2` O

效果如下：

H₂O

上标

rst如下：

E = mc :sup:`2`

效果如下：

E = mc²

参见

更多说明，详见rst文档：http://docutils.sourceforge.net/rst.html

另外，这本书本身就是个示例：https://github.com/akun/pm

Hello World

根据上面的介绍，其实常用的语法不多，现在直接用下，自己感受下吧！

安装 & 初始化

常用Python安装方式，创建个文件夹，执行命令，按提示自己选择即可。

pip install Sphinx
mkdir docs
cd docs
sphinx-quickstart

根据提示输入相应参数即可，可以一路默认。

尝试编辑

编辑index.rst，只写入以下内容

用Sphinx编写技术文档
====================
使用场景
--------

生成HTML

很简单，默认支持就很好。

make html
python -m SimpleHTTPServer 9527

直接浏览器访问9527端口，就可以看到类似Python官方文档的效果。

生成PDF

麻烦些，需要依赖库，且需要简单修改下配置。

安装依赖库

pip install rst2pdf

编辑conf.py，增加或修改如下配置：
编辑Makefile，增加如下代码：

Linux下的Makefie：

Windows下的批处理：

执行生成PDF

make pdf
python -m SimpleHTTPServer 9527

参见

有关PDF的更多配置，可以阅读这个文档：http://ralsina.me/static/manual.pdf

生成Slide

Slide就是我们常说的演示文档，如：Windows下的PowerPoint（PPT）；Mac下Keynote等等。这里用Sphinx生成在线的HTML5形式的Slide，操作也相对简单，也是需要依赖库和简单修改下配置。

安装依赖库

pip install hieroglyph

编辑conf.py，修改如下配置：
编辑Makefile，增加如下代码：

Linux下的Makefie：

执行生成Slides

make slides
python -m SimpleHTTPServer 9527

参见

有关Slide的更多信息，可以直接查看这个项目：https://github.com/nyergler/hieroglyph

自定义样式

直接拿来主义，直接用别人写的Trac的样式

复制样式文件到静态资源目录，比如，这里是：

cp tracsphinx.css _static/

编辑conf.py，增加或修改如下配置：
执行生成HTML

make html
python -m SimpleHTTPServer 9527

直接浏览器访问9527端口，就可以看到类似Trac的官方样式效果。

汇总到一块

可以直接看Python项目模板：https://github.com/akun/aproject/只看docs目录即可。

这里提到的几个核心文件示例如下：

index.rst

conf.py

Makefile

css

另外推荐一个服务：https://readthedocs.org/

如果你的项目研发文档用Sphinx写的，可以用来做文档的持续集成，相当方便。

这个《软件构建实践系列》就是用的这个服务。

最后

这是一篇很简单的项目推广文章，在自己的Python项目中把Sphinx用起来吧！

当然Sphinx不仅支持Python源码的Domain，而且支持C、C++、JavaScript等Domain，即使没有你所用的语言的Domain，它本身还支持写插件扩展，所以其它类型语言的项目也不妨用一下。

注解

这篇是个人总结的《软件构建实践》系列的一篇文章，更多更新内容，可以直接在线查看：http://pm.readthedocs.org。并且部分内容已经公布在GitHub上：https://github.com/akun/pm

原文地址：用Sphinx编写技术文档, 感谢原作者分享。

热心网友时间：2022-05-06 07:38

你可以使用doxygen或者Sphinx，现在python文档就是使用Sphinx生成的，你可以到官网看一下具体的使用方法。

热心网友时间：2022-05-06 08:56

python有专门的模块：pydoc 来生成文档。用法很容易查到。

热心网友时间：2022-05-06 10:31

Sphinx 大部分文档都是它生成的 http://sphinx-doc.org/#