python-sphinxpython-sphinx入门


备注

本节概述了python-sphinx是什么,以及开发人员为什么要使用它。

它还应该提到python-sphinx中的任何大型主题,并链接到相关主题。由于python-sphinx的文档是新的,您可能需要创建这些相关主题的初始版本。

安装或设置

由于SphinxPython Package Index上可用,因此可以使用pip进行安装:

pip install Sphinx
 

或者您也可以使用easy_install进行安装

easy_install -U sphinx
 

然后,您可以通过执行以下命令来检查它是否已正确安装:

> sphinx-quickstart --version
Sphinx v1.4.1
 

在继续之前,您需要遵循python PEP 8的某些代码样式。如果您已遵循PEP 8指南,则可以在sphinx中定义文档结构并开始构建文档

快速开始

要开始,请转到项目目录的根目录并运行:

$ sphinx-quickstart
 

您将获得为项目创建文档的选项。对于默认设置,请遵循以下命令

Prompt    Choice
> Root path for the documentation [.]:    <ENTER>
> Separate source and build directories (y/N) [n]:    y
> Name prefix for templates and static dir [_]:    <ENTER>
> Project name:    an_example_pypi_project
> Author name(s):    Andrew Carter
> Project version:    0.0.1
> Project release [0.0.1]:    <ENTER>
> Source file suffix [.rst]:    <ENTER>
> Name of your master document (without suffix) [index]:    <ENTER>
> autodoc: automatically insert docstrings from modules (y/N) [n]:    y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:    n
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:    y
> todo: write “todo” entries that can be shown or hidden on build (y/N) [n]:    n
> coverage: checks for documentation coverage (y/N) [n]:    n
> pngmath: include math, rendered as PNG images (y/N) [n]:    n
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:    n
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:    y
> Create Makefile? (Y/n) [y]:    n
> Create Windows command file? (Y/n) [y]:    n
 

成功执行后,您可以在项目的doc / source目录中发现config.py文件。此文件可以控制运行build命令时文档生成方式的基本结构,如下所示

$ sphinx-build -b html sourcedir builddir

有关详细说明,请访问: https ://pythonhosted.org/an_example_pypi_project/sphinx.html