# Sphinx 快速入门

Sphinx是一个强大的文档生成工具，尤其适合编写技术文档，可以使用reStructuredText（推荐）或者Markdown语法进行标记文档写作。它可以令人轻松的撰写出清晰且优美的文档。

官网定义：Python Documentation Generator（原来定位是为Python项目设计的首选文档工具）

特性

丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本
完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
美观的自动索引: 可自动生成美观的模块索引
精确的语法高亮: 基于 Pygments 自动生成语法高亮
开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等

摘自：Sphinx 使用手册

安装Sphinx

假定你已经安装了Python，接下来安装Sphinx:

$ pip install sphinx

初始化文档项目

你的文档项目目录下创建一个文件夹docs用于存放你的文档。

$ cd /path/to/project

$ mkdir docs

运行初始化

$ cd docs

$ sphinx-quickstart

这个命令会一步一步引导你进行基本配置，一般情况下你可以使用默认值即可。设置完成后，会建立 index.rst 和conf.py 配置文件已经其它一些文件，你可以把它们添加到版本控制。现在你可以进一步编辑index.rst,这是文档的入口。

source目录下的conf.py文件为sphinx的配置文件。

生成html并预览

注意：生成 html 格式的文档时，记得先清空（删除）build文件夹。

$ make clean

$ make html

这个命令把你的index.srt 文件生成index.html，放在你的文档输出文件夹内（典型例子是_build/html/index.html)，在你的浏览器中打开它以预览你的文档。

你可以修改你的文件并重构(rebuild)，直到你对文档效果满意为止。这时，你可以提交(commit)你的修改，上传(push)到公共仓库。

一旦有Sphinx 文档在公共仓库中，你就可以开始使用Read the Docs，导入(importing)你的文档。编译文档,构建并生成预览(web)

为了避免潜在的不兼容，强烈建议你在项目中指定版本(本站主的是v3.4.3)：

# docs/requirements.txt

sphinx==3.2.1

sphinx_rtd_theme==0.5.0

在Shpinx中使用Markdown

可以在同一个Sphinx项目中同时使用Markdown和reStructuredText。

$ pip install recommonmark

然后在 conf.py文件中:

extensions = ['recommonmark']

预览

cat license.rst | pbcopy

主题

Sphinx 为我们提供了好多可选的主题，参见：Sphinx Themes----A showcase for Sphinx documentation themes。

这里使用的是： Read the Docs Sphinx Theme

Installation:

This theme is distributed on PyPI and can be installed with pip:

$ pip install sphinx-rtd-theme

To use the theme in your Sphinx project, you will need to add the following to your conf.py file:

import sphinx_rtd_theme

extensions = [
    ...
    "sphinx_rtd_theme",
]

html_theme = "sphinx_rtd_theme"

For more information read the full documentation on installing the theme

Sphinx实战

sphinx侧边栏自定义

默认不修改，就可以支持目录以及目录的展开（一般不需要设置）。也可以自定义边栏样式，设置方法：

新建一个template文件，如 mytoc.html
编辑conf.py文件（sphinx设置文件），找到html_sidebars，修改配置主题选项

html_sidebars = {

‘**’: [‘addtoc.html’, ‘relations,html’, ‘searchbox.html’]

}

生成，左边主题即按照mytoc.html模版的样式显示

一个可展开目录的模版如下：toctree及括号间无空格编译不过加的(编者注)

#file mytoc.html
{ { toc tree(collapse=True)} }

修改文档语言为中文

找到#language = None，修改为：language ='zh_CN'，其它语言见下表:

bn – Bengali
ca – Catalan
cs – Czech
da – Danish
de – German
en – English
es – Spanish
fi – Finnish
fr – French
hr – Croatian
it – Italian
ja – Japanese
lt – Lithuanian
nl – Dutch
pl – Polish
pt_BR – Brazilian Portuguese
ru – Russian
sl – Slovenian
tr – Turkish
uk_UA – Ukrainian
zh_CN – Simplified Chinese
zh_TW – Traditional Chinese

增加 logo 图片

自带了一个logo 位置

    # 在 conf.py 之中指定 logo 图片 ,相对于 conf.py 的文件路径
    html_logo = './_static/logo.jpg'

实现文档团队全球在线协作

工具组合：

Typora + GitBook + Markdown + GitHub
Typora(or Notepad++) + Sphinx + reStructuredText(or Markdown) + Read the Docs + GitHub

如果无服务器，想托管，可以先用 Sphinx 生成文档，然后用 GitHub 托管文档，再导入到 Read the Docs 生成在线文档。

Read the Docs 是一个基于 Sphinx 的免费文档托管项目。

中文建议文件编码：UTF-8

好处:

语法简单
兼容性强
导出方便
专注内容
团队协作

参见

本文部分内容摘自：https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html

知识库

Sphinx文档生成工具

特性