使用Sphinx编辑python程序

最近需要些API文档，简单研究了一下。这里仅作为记录，各位能参考则好，不能请自行研究。

一：什么是sphinx

http://www.pythondoc.com/sphinx/contents.html

 Sphinx是一个可自动生成python项目api的工具，只需要在项目上进行简单的配置，即可生成项目的api文档。当然C++项目也是可以生成的。

二：python开发环境配置

此处使用的是pycharm。需要安装sphinx，同时安装sphinx_rtd_theme.

sphinx_rtd_theme是一种在线的显示主题。

非必要设置。

 三：你的.py文件夹位置

 四：在test_sphinx文件下新建一个doc文件夹

 五：使用命令行到doc文件夹下

 

 然后输入命令：sphinx-quickstart进行配置。

 第一个红框中输入Y，此处是source文件夹和build是否分离放置，一般分离放置。

第二个铝框中是你需要输入的信息。

如图所示：项目名称，作者名称，版本号。

第三个黄框中是你需要输入的项目语言。

黄框中有网址可以查看有哪些支持的语言。如下图所示：

       

 此时doc文件夹中为：

 

六：生成各个.py文件的.rst文件

 使用命令：

sphinx-apidoc -o [生成rst的位置] [项目代码的位置] -f(强制重新覆盖写，否则会检测，如果有同名文件存在，会跳过不更新)
sphinx-apidoc -o rst ../Tensor   (项目代码的位置根据你的实际情况填写)

 

 

 七：修改conf.py文件

将下面红框的注释取消，并将绿框中的你的程序的位置设置正确。

 下图是我的设置：

 因为conf.py需要取得Tensor文件中的源程序，所以需要将abspath设置到Tensor文件夹中。

然后添加：import sphinx_rtd_theme。更换主题显示。

 同时原来的html_theme也要更换为下图所示。

 还有一个地方，因为某些问题会报错，也需要更改。

通常使用下列两种就能解决很多问题，如果还有其他问题请自行google。

 八：将rst文件挪到source文件夹下

 如果不将文件放置在此文件下，会发现很多文件找不到，还有一些其他问题。

九：配置index.rst文件

配置前状态：

 配置后：加入自己的Tensor.rst文件。删除上图中的黄框是为了减去一些不必要的显示而已。没有尝试过的可以自己试试再删除或者保留。

 十：使用make html生成

生成结果在一开始分离的build中的html文件中。

 

 

 

 Tensor Module中就是你的.py文件显示。

END!

补充：自己写.rst文件。下面仅作为记录。

Tensor module
=============

.. automodule:: Tensor
.. automethod:: Tensor.fromarray

Examples::

  >>> a = np.array([1, 2]).astype(np.float32)
  >>> t = Tensor.fromarray(a)
  >>> t.info()
  >>> t.print()