摘要：简介是一个用于快速生成文档的工具，非常适合生成文档。称之为主文档，它被作为欢迎页面。由于是默认的域，所以并不需要特别指出所属的域来。自动生成文档注释支持从源代码中提取文档注释信息，然后生成文档，我们将这称之为。
简介
sphinx是一个用于快速生成文档的工具，非常适合生成Python文档。
它具有以下优点：
支持多种输出格式， 如html，Latex，ePub等。
丰富的扩展
结构化文档
自动索引
支持语法高亮
sphinx使用reStructuredtext作为它的标记语言。
安装使用pip进行安装：
pip install sphinx设置源文件目录
包含.rst文件的根目录称之为源文件目录，目录中还包含sphinx的配置文件conf.py。
进入源文件目录，执行以下命令，会指引用户配置整个项目：
sphinx-quickstart定义文件结构
执行上述命令之后，sphinx会在源文件目录中自动生成conf.py文件以及index.rst。index.rst称之为主文档，它被sphinx作为欢迎页面。
index.rst中包含了目录树指令toctree，sphinx使用它链接其他子文档。
toctree指令的初始值为空：
.. toctree:: :maxdepth: 2
接下来就可以给它添加子文档的链接了，直接使用文档的名称即可，省略掉文件后缀，如果是多级目录，则使用/分隔开。
.. toctree:: :maxdepth: 2 intro tutorial chapter/doc1 ...
接着我们就可以创建上面列出的文件并添加相应内容了，sphnix会自动将这些文档的章节标题插入到doctree指令的位置。
添加内容在sphinx源文件中，使用reStructuredText标记语言进行文档编写，除此之外，sphinx还格外提供了一些指令。
具体可以参考
生成文档reStructuredText Primer 以及
Sphinx Markup Constructs
使用下面的命令生成文档：
$ sphinx-build -b html sourcedir builddir
sourcedir指源文件目录，生成的文档放置在builddir指定的目录中。
实际上还有一个更简便的方法，sphinx-quickstart生成了一个make.bat文件，可以直接运行这个脚本：
make html
上述命令会直接在源文件目录中生成文档。
对象文档sphinx的设计初衷之一就是更容易生成任何域中对象的文档，域指很多对象的集合，这些对象中还包含了相应的文档注释。
最主要的域是Python域， 例如python内置函数enumerate()的注释文档如下所示：
.. py:function:: enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the *sequence*. (And so on.)
它将被渲染成如下格式：
enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)
指令参数是我们需要描述的对象，内容是我们编写的文档注释。由于Python是默认的域，所以并不需要特别指出所属的域来。
.. function:: enumerate(sequence[, start=0]) ...
sphinx还提供了一些指令用于生成其他对象类型的文档。例如py:class以及py:method
基本配置sphinx通过conf.py进行配置，conf.py使用python语法，默认以utf-8编码保存。具体配置请查看 The build configuration file。
自动生成文档注释sphinx支持从python源代码中提取文档注释信息，然后生成文档，我们将这称之为autodoc。
为了使用autodoc，首先需要在配置文件的extensions选项中添加"sphinx.ext.autodoc"。然后我们就可以使用autodoc的指令了。
例如，生成函数io.open()的文档，只需要在rst文件中添加如下语句：
.. autofunction:: io.open
也可以直接生成整个类的文档：
.. automodule:: io :members:
为了提取文档注释，autodoc需要导入注释所在的模块。因此需要在sys.path中设置好模块的路径。
设置主题推荐使用readthedoc使用的主题，美观又简洁大方。
首先安装主题库：
pip install sphinx_rtd_theme
然后配置conf.py:
import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
简书地址
文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。
转载请注明本文地址：https://www.ucloud.cn/yun/38214.html
摘要：一介绍与好处介绍本身是一个中文检索索引技术索引主键唯一普通全文是俄罗斯人开发一款速度效率非常高的索引技术是来替代全文索引的本身的全文索引技术特性表现一般，一般数据库使用全文索引都不是使用本身的，都需要借助第方索引技术支持，搜索引擎百 一．sphinx介绍与好处 介绍 sphinx本身是一个中文检索索引技术 mysql索引： 主键、唯一、普通、全文(match/agaisnt)sphi...
摘要：使用第二版的扩展匹配模式对查询进行匹配强制使用下文所述的完整扫描模式来对查询进行匹配。并且可以在服务器端设定当前查询的结果集大小，另有一个阈值，当找到的匹配项达到这个阀值时就停止搜索。 Sphinx 简介 Sphinx 说明我这就不多说了，有兴趣的朋友可以点击 编译安装sphinx-0.9.9全文检索 去看详情~！ sphinx中文手册 创建Sphinx索引 source src_bl...
摘要：使用第二版的扩展匹配模式对查询进行匹配强制使用下文所述的完整扫描模式来对查询进行匹配。并且可以在服务器端设定当前查询的结果集大小，另有一个阈值，当找到的匹配项达到这个阀值时就停止搜索。 Sphinx 简介 Sphinx 说明我这就不多说了，有兴趣的朋友可以点击 编译安装sphinx-0.9.9全文检索 去看详情~！ sphinx中文手册 创建Sphinx索引 source src_bl...
阅读 5748·2021-11-24 10:25
阅读 2691·2021-11-16 11:44
阅读 3845·2021-10-11 11:09
阅读 3173·2021-09-02 15:41
阅读 3257·2019-08-30 14:14
阅读 2276·2019-08-29 14:10
阅读 2346·2019-08-29 11:03
阅读 1126·2019-08-26 13:47
