本文介绍如何使用Sphinx工具从reStructuredText或Markdown格式的文件生成技术文档，支持多种输出格式，如HTML、PDF和ePub，并可托管到GitHub和readthedocs。

文中详细讲解了安装过程、目录结构和配置文件的修改。

sphinx安装及简单使用

如果你要编写技术文档, 可以用 reStructuredText 或 Markdown 格式编辑文件，然后使用 Sphinx 工具转换成 html, PDF, ePub等格式，或者托管到 github并导入 readthedocs 网站。

1.安装软件包（需要先安装 Python）

pip install sphinx sphinx_intl sphinx_rtd_theme recommonmark

sphinx: 文档生成工具
sphinx_intl: 多语言工具
recommonmark: sphinx支持markdown的插件
sphinx_rtd_theme: sphinx的readthedocs主题插件

2.创建存放文档的目录，执行 sphinx-quickstart 命令

cd /path/to/project
mkdir docs
cd docs
sphinx-quickstart

sphinx-quickstart 会创建基本配置。一般情况下，你只要接受默认值就行了。当上述命令执行完后，在 docs目录下，你会找以 index.rst和 conf.py。 你可以编辑这两个文件，加入一些项目信息。

Makefile : 批处理指令，使用 make 命令时，用来构建文档输出。

_build : 用于存放最终生成的文档。

_static : 所有不属于文档源代码的文件（如图像）均存放于此处，构建时会它们链接在一起。

conf.py : 一个 Python 文件，存放 Sphinx 的配置值，包括执行 sphinx-quickstart 时选中的那些值。

index.rst : 文档项目的 root 目录。如果将文档有多个文件，该目录会连接这些文件。

3.修改conf.py，加入 Markdown 支持

extensions = ['recommonmark']

4.修改 conf.py，使用 sphinx_rtd_theme 风格。修改

html_theme = 'alabaster'

为

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

5.执行命令，cmd生成输出 

添加好系统环境变量路径 

make html

输出的html文件在 docs\_build\html目录下， 打开 index.html即可。