专栏首页nummysphinx入门指南【1】快速入门

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 条评论
登录 后参与评论

相关文章

  • 浅谈jQuey表单序列化

    jQuery表格中提供了两个表格序列化函数。分别是serilize()和serializearray()。

    用户2936342
  • sphinx入门指南【2】 toctree指令详解

    reST本身并不支持同时与多个文档进行交互,或者说将一个文档保存到多个文件中。Sphinx提供了自定义指令toctree来支持实现这个功能。

    用户2936342
  • Circus入门教程

    Circus是与supervisor类似的进程监控工具,它也是使用Python编写的。

    用户2936342
  • Indesign怎么创建单排排列的文档?

    Indesign中想要创建单排排列的文档,该怎么创建呢?下面我们就来看看详细的教程。

    砸漏
  • Typora 在 windows 下图片的保存设置

    在使用Typora编写markdown格式的时候,我有个痛点问题。就是在windows下,我保存的图片和文档不方便拷贝到其他电脑。

    Devops海洋的渔夫
  • 这个在线文档工具, 让我上头了!

    话不多说,开始使用 点此进行注册 邀请码:9aa8d536 (动动小手填写下吧. 谢谢大家了)

    时间静止不是简史
  • 苹果,你的开发者文档写得烂透了!!!

    苹果的 App Store 审核之严格,大家都有所耳闻。但在苹果公司的平台上写代码,似乎却不是那么一件令人身心愉快的事儿。本文主人公 Chris Krycho ...

    GitHubDaily
  • Sphinx补篇

    我的写作习惯是用到的参考资料直接发出来,在阅读起来可能有一丝割裂感.但是在学习的感觉上是,由浅入深,由浅入深的感觉,以下的所有文章都是这样........

    云深无际
  • 质量管理体系之如何使用测试文档模板?

    张树臣
  • python可视化文本分析-分析Q群聊天记录(一)

    代码开箱可用,你需要把你的文件名替换正确的路径,还有要在同级目录下创建img文件夹保存生成的两张图片。各种依赖环境很简单,直接pip install xxx。 ...

    bigsai

扫码关注云+社区

领取腾讯云代金券

,,