专栏首页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()]
本文参与 腾讯云自媒体分享计划 ,欢迎热爱写作的你一起参与!
本文分享自作者个人站点/博客:https://www.jianshu.com/u/69ba0aedbe3c复制
如有侵权,请联系 cloudcommunity@tencent.com 删除。
登录 后参与评论
0 条评论

相关文章

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

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

    用户2936342
  • Cobbler 快速入门指南

    KangVcar
  • 快速入门 Akka Java 指南

    Akka 是一个用于在 JVM 上构建高并发、分布式和容错的事件驱动应用程序的运行时工具包。Akka 既可以用于 Java,也可以用于 Scala。本指南...

    CG国斌
  • Shell编程快速入门指南

    字符串可以使用单引号和双引号,单引号中不能包含单引号,即使转义单引号也不次那个,双引号则可以,双引号也可以使用字符串。

    用户1515472
  • SOAR 101 快速入门指南

    soar开源两周以来,在Github获得了社区2700+颗星的支持,这期间有很多的开源社区同学参与到soar的成长当中,为我们提供了许多优秀的意见和建议。

    DevOps云学堂
  • Apache Cassandra 快速入门指南

    我们在这篇文章简单介绍了 Apache Cassandra 是什么,以及有什么值得关注的特性。本文将简单介绍 Apache Cassandra 的安装以及简单使...

    大数据和云计算技术
  • 容器快速入门完全指南

    容器,以及Docker和Kubernetes之类的容器技术已经日益成为许多开发人员工具包中常见的工具。容器化的核心目标是提供一种更好的方式,以可预测和便于管理的...

    CNCF
  • markdown 快速入门之掘金入门指南 原

    欢迎使用 掘金-Markdown 编辑器撰写技术文章,只专注于内容和技术,不再费心排版的问题。这是一份简要的 Markdown 引导指南,希望可以帮助您顺利的开...

    雪之梦技术驿站
  • 云计算快速入门指南

    简单来说,云计算就是按需计算服务的交付,服务涵盖:应用程序、存储和处理能力,通常通过互联网并按需付费。

    SDNLAB
  • MyBatis(1)——快速入门

    MyBatis 简介 MyBatis 本是apache的一个开源项目iBatis, 2010年这个项目由apache software foundation 迁...

    我没有三颗心脏
  • springboot(1)--快速入门

    Spring Boot可以轻松创建可以运行的独立的,生产级的基于Spring的应用程序。我们对Spring平台和第三方库进行了一种自以为是的观点,这样您...

    叔牙
  • EFK教程 - EFK快速入门指南

    通过部署elasticsearch(三节点)+filebeat+kibana快速入门EFK,并搭建起可用的demo环境测试效果

    小慢哥Linux运维
  • FastAPI--快速入门(1)

    注意事项,因为FastAPI仅支持Python3.6+的API,所以需要再Python3.6+的环境进行学习实践!

    py3study
  • Python 爬虫 1 快速入门

    Python 爬虫 快速入门 参考资料:极客学院: Python定向爬虫 代码:1.crawler-basic.ipynb 本文内容: 正则表达式 用正则表达式...

    杨熹
  • Spring学习(1)——快速入门

    认识 Spring 框架 Spring 框架是 Java 应用最广的框架,它的成功来源于理念,而不是技术本身,它的理念包括 IoC (Inversion of ...

    我没有三颗心脏
  • Cloudera 系列1:Cloudera 入门指南

    问题导读 1.Cloudera 提供了那些产品和工具? 2.Cloudera Navigator的作用是什么? Cloudera 提供一个可扩展、灵活、...

    用户1410343
  • Gatsby入门指南—支持Markdown(1)

    前端大彬哥

扫码关注腾讯云开发者

领取腾讯云代金券