用sphinx生成python文档

发表于   |  

Sphinx

简介

我们在网上看python的文档的时候会发现很多开源项目都有相应的文档。并且这些文档都是相似的，很整洁。所有这些都是托管在https://readthedocs.org/上(readthedocs可以连接到github)。

开始

首选运行命令，生成doc工程

1
sphinx-quickstart

  • 文档根目录(Root path for the documentation)，默认为当前目录(.)
  • 是否分离文档源代码与生成后的文档(Separate source and build directories): y
  • 模板与静态文件存放目录前缀(Name prefix for templates and static dir):_
  • 项目名称(Project name) : EvaEngine
  • 作者名称(Author name): Bondlee
  • 项目版本(Project version) : 1.0.1
  • 文档默认扩展名(Source file suffix) : .rst
  • 默认首页文件名(Name of your master document):index
  • 是否添加epub目录(Do you want to use the epub builder):n
  • 启用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode：y
  • 生成Makefile (Create Makefile)：y
  • 生成windows用命令行(Create Windows command file):y

最后会生成Sphinx一个文档项目必需的核心文件，包括：

  • Makefile：编译过代码的开发人员应该非常熟悉这个文件，如果不熟悉，那么可以将它看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
  • _build：这是触发特定输出后用来存放所生成的文件的目录。
  • _static：所有不属于源代码（如图像）一部分的文件均存放于此处，稍后会在构建目录中将它们链接在一起。
  • conf.py：这是一个 Python 文件，用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart 时选中的那些值。

  • index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。

    readthedocs
│ make.bat
│ Makefile
├─build
└─source
  │ conf.py
  │ index.rst
  ├─_static
  └─_templates

rst语法

rst与markdown的格式很像，不过功能上比markdown要强大很多。可以输出转换为html、pdf和slides。
toctree示例

Contents:

.. toctree::
   :maxdepth: 2

   example

conf.py

conf.py是用于配置sphinx生成文档时使用的,使用quikstart时的问题就是全部填入cron.py中，若填问题的时候发现了不对的地方，可以在cron.py中自己修改。例如我在automode中填了no，即不会自动抽取代码中的注释生成文档。

1
2
3
4
5
6
7
8
extensions = [
       'sphinx.ext.doctest',
       'sphinx.ext.todo',
       'sphinx.ext.coverage',
       'sphinx.ext.pngmath',
       'sphinx.ext.ifconfig',
       'sphinx.ext.viewcode',
   ]

则需要在extensions中加入sphinx.ext.autodoc

1
2
3
4
5
6
7
8
9
extensions = [
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.pngmath',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.autodoc',
]

Sphinx-apidoc生成文档

  • 修改source中的conf.py文件。目的是确保python源代码所在的包在系统路径中可以找到。
    将
1
2
3
#sys.path.insert(0,os.path.abspath('.'))
改为,并去掉注释
sys.path.insert(0,os.path.abspath('..'))
  • 生成rst文件,outputdir是source的目录，packagedir是代码所在的目录
1
sphinx-apidoc -o outputdir packagedir

sphinx-apidoc的参数：

  • -o rst输出文件夹
  • -f, –force 强制输出，已经生成的rst会被覆盖.
  • -l, –follow-links 符号链接
  • -n, –dry-run If given, apidoc does not create any files.
  • -s Suffix for the source files generated, default is rst.
  • -d Maximum depth for the generated table of contents file.
  • -T, –no-toc Do not create a table of contents file.
  • -F, –full If given, a full Sphinx project is generated (conf.py, Makefile etc.) using sphinx-quickstart.
  • -e, –separate Put each module file in its own page.
  • -E, –no-headings Don’t create headings for the modules/packages
  • -P, –private
  • -H Project name to put into the configuration.
  • -A Author name(s) to put into the configuration.
  • -V 工程版本
  • -R 工程发布版本

其中：

  • 生成rst文件后，就可以生成html文件了。进入到source目录下，运行：
    1
    sphinx-build -b html sourcedir outputdir

会在source目录下生成outputdir文件夹，并且生成的html文件都在outputdir文件夹内。

在quik-start中生成的目录，以上命令都可以被make命令替代：

1
make html

运行

生成html后就可以使用了。