python2以及python3使用sphinx生成文档

assumption object is test-project and in venv

(venv) zuo-MacBook-Pro:~/test-project$mkdir doc
(venv) zuo-MacBook-Pro:~/test-project$cd doc
(venv) zuo-MacBook-Pro:~/test-project/doc$

sphinx官方文档：http://www.sphinx-doc.org/en/master/

---

转：http://davidstutz.de/setting-up-sphinx-for-documenting-python-projects/

install

For Python 2.x usage:

(venv)$ sudo apt-get install python-sphinx

Alternative:

(venv)$ python -m pip install sphinx # To make sure pip corresponds to Python 2.x

For Python 3 usage:

(venv)$ sudo apt-get install python3-sphinx

Alternative:

(venv)$ python3 -m pip install sphinx

---

转：https://www.jianshu.com/p/d4a1347f467b

(venv) zuo-MacBook-Pro:~/test-project/doc$ sphinx-quickstart 
Welcome to the Sphinx 1.5.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: .

> Separate source and build directories (y/n) [n]: y

> Project name: Code Pro
> Author name(s): Allen Woo

> Project version []: 1.0

> Project language [en]: zh_cn

> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y

2.配置conf.py
在source/conf.py文件中加入如下代码， 导入自己的项目路径

import os
import sys
sys.path.insert(0, os.path.abspath('./../../code'))

1. 生成rst文件
   注意:-o 后面跟的是保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录。然后在后面的是你的项目(代码)路径

(venv) zuo-MacBook-Pro:~/renren/doc$ sphinx-apidoc -o ./source ../code/
Creating file ./test1.rst.
Creating file ./test2.rst.
Creating file ./modules.rst.

1. 最后执行make html,生成html文件

(venv) zuo-MacBook-Pro:~/renren/doc$ make html
Running Sphinx v1.5.5
loading translations [zh_cn]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

Build finished. The HTML pages are in build/html.

安装Sphinx主题
python sphinx的主体包邮很多，我最喜欢 readthedocs风格的：
这种风格的sphinx主体包叫sphinx_rtd_theme
可以下载安装，也可以命令安装。

命令安装：

pip install sphinx_rtd_theme

下载地址：
https://github.com/rtfd/sphinx_rtd_theme
注意：下载安装的配置和使用命令安装的不一样，具体可以看GIthub上的文档：

配置：
编辑我们的source/conf.py
导入模块：

import sphinx_rtd_theme

将 html_theme = “alabaster”改成如下，在加上html_theme_path

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

最后我们再执行一次：make html
然后再访问文档，发现里面变的好看了，是不是？

---

转：https://blog.csdn.net/preyta/article/details/73647937

source/ 目录

source/目录里有两个文件，分别是conf.py和index.rst，下面对它们进行进一步的介绍

index.rst

.rst是reStructuredText，和Markdown一样是一种标记语言，具体的语法可以看这里 reStructuredText Primer。
实际上，我们在使用Sphinx的过程中最主要就是对这些rst文件进行修改，而Sphinx所做的事情就是读取这些rst文件，并转换为特定格式的文档，在前面的步骤中，index.rst实际上被转换为build/html/index.html，而实际上在rst文档内你可以写任何东西，最后这些都会被转换到输出文档中。

打开index.rst,可以看到这样的内容，这是rst的一个语法，它使用了一个toctree节点，并设置了一些参数，而这个toctree节点是必须的。

.. toctree::
  :maxdepth: 2
 :caption: Contents:

conf.py

这是运行sphinx生成文档时会加载的配置，你可以通过对它进行修改来改变生成文档的行为。

一个具体的例子
假设现在我们有一个叫run.py的文件，如下

run.py

def run(name):
"""
this is how we run

    :param name name of people who runs
    """
    print name, 'is running'

那么需要如何生成文档呢？下面一步步带你完成
- 创建一个文件夹demo/，并将run.py放到里面
- 在demo里创建一个docs目录，进入docs/目录，当然这里你可以随意选定文件夹，只是这样更规范一些
- 生成Sphinx默认模板，设置项目名为demo，并开启autodoc
运行sphinx-quickstart
- 进入source目录，打开index.rst
- 将index.rst 修改为如下，实际上这里面可以写任何满足rst规范的内容

Welcome to demo's API Documentation
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Introduction
============
This is the introduction of demo。

API
===
.. automodule:: run
   :members:

Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

这个是用于自动从模块读取docstring的语句，可以自动从run模块读取文档

.. automodule:: run
   :members:

但是现在还差一步，如果你现在直接生成文档，会告诉你找不到run模块，因为Sphinx默认只会从sys.path里加载模块，所以需要将demo目录加入sys.path，所以现在打开conf.py，添加如下内容

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

运行Sphinx生成html文档

cd ..
sphinx-build -b html source build
make html

现在，打开build/html/index.html就可以看到了

格式进一步优化

上面的例子涵盖了大多数常用操作，但是通常文档都不是扁平的，而是层次化的，那么要如何将文档层次化的分门别类。
实际上在rst文档中是可以以链接的形式引用其他rst文档的，也就是说我们可以自由的对文档结构进行组织使其更易读

下面我们把run的文档移动到一个单独的页面，只在index.rst里保留跳转链接。在source目录下创建run.rst

API
===
.. automodule:: run
   :members:

Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

然后将index.rst对应位置的内容删掉，并进行修改

Welcome to demo's API Documentation
===================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Introduction
============
This is the introduction of demo。

API
===
:doc:'Run API</run>'

Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

:doc:’Run API’表示对一个文档的引用，这里引用了当前目录的run.rst，现在重新生成html，就会看到页面显示上的变化了。

---

官方文档：http://www.sphinx-doc.org/en/master/