sphinx入门指南【1】快速入门

简介

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()]

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏Java后端技术

一段奇妙的vim编辑器之旅

  对于Linux服务器上的操作,我们往往少不了使用vim,而有时候我对vim的使用并没有那么的熟练和深入,这周就深入的学习了vim的使用,包括入门和进阶,先分...

813
来自专栏抠抠空间

Django之auth模块(用户认证)

auth模块简介 auth模块是对登录认证方法的一种封装,之前我们获取用户输入的用户名及密码后需要自己从user表里查询有没有用户名和密码符合的对象, 而有了a...

4345
来自专栏逍遥剑客的游戏开发

Tiled源码分析(四): 插件机制

2287
来自专栏magicsoar

初识nginx——配置解析篇

一、nginx的介绍     nginx是由俄罗斯人开发的一款高性能的http和反向代理服务器,也可以用来作为邮件代理。相比较于其他的服务器,具有占用内存少,稳...

2688
来自专栏码洞

自己动手实现 Shell多进程套套符

一篇技术文章如今仅仅是理论上讲得天花乱坠,却不能自己撸出东西来,那么它写的再好,也只能算纸上谈兵。继上一篇 《我们天天都在使用的套套符命令,Shell 在里面到...

981
来自专栏风中追风

分布式进阶__如何用zookeeper 实现分布式锁

        分布式锁主要用于在分布式环境中保护跨进程、跨主机、跨网络的共享资源实现互斥访问,以达到保证数据的一致性。

39216
来自专栏深度学习之tensorflow实战篇

python(Django之html模板继承)

Django之html模板继承简单案例 1 构建母板,确定不变内容和可变内容 ? 2 构建子板,对可变内容进行填充 ? 结果: ? Dja...

3885
来自专栏代码GG之家

深入Android源码系列(二) HOOK技术大作战

漫天的标题党的口水文打赏爆表,冷落了一群默默输出高质量文章的人群。真正的技术文章能否得到认可? 本文讲解内容有 hook技术原理探究 ...

2455
来自专栏Android随笔

mac学习笔记

在打开的文本文件中,添加如下内容(/XXX/XXX/platform-tools/为你的adb路径)

762
来自专栏xingoo, 一个梦想做发明家的程序员

[logstash-input-redis]插件使用详解

Redis插件参数配置详解 最小化配置 input { redis { data_type => "list" #logstash redis插件工作方式 ...

2978

扫码关注云+社区