Sphinx使用笔记

发表于 更新于 分类于 ， ， 本文字数： 6.7k 阅读时长 ≈ 7 分钟

记录一下学习使用Sphinx的相关知识和要点, 以备后续查阅

关联关系

reStructuredText

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems.

The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.

See statemachine.py for an example of a Python module fully documented using reStructuredText.

译文如下:

reStructuredText是一个易于阅读的，所见即所得的纯文本标记语法和解析器系统。它对于内嵌程序文档（如Python docstrings）、快速创建简单网页以及独立文档都很有用。reStructuredText设计用于特定应用程序域的可扩展性。reStructuredText解析器是Docutils的一个组件. reStructuredText是对结构化文本的修订和重新解释和Setext轻量级标记系统。

reStructuredText的主要目标是定义和实现一个标记语法，以便在Python文档字符串和其他文档域中使用，该语法可读、简单，但功能强大，足以用于非平凡的用途。标记的目的是将reStructuredText文档转换为有用的结构化数据格式。

参见statemachine.py有关使用reStructuredText完整记录的Python模块的示例。

RST文档格式支撑了Sphinx项目, 属于项目的前置应用, 因此需要学习相关语法, 更多参见.

Sphinx

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档 就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:

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

Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析，转换等多种工具.

ReadtheDocs

Read the Docs是一个基于Sphinx的免费文档托管项目，目前已经托管了超过90000份文档。2011年3月9日，Python软件基金会曾给Read the Docs拨款840美元供服务器托管[1]，2017年11月13日Linux Mint宣布将所有文档转移到Read the Docs。[2][3]

Read the docs是目前十分通用的样式美观, 结构清晰, 便于使用的一个文档框架, 许许多多开源软件都使用了RTD的框架或主题, Sphinx也有RTD的相关主题, 因此需要学习如何配置, 更多参见.

要点记录

reStructuredText

语法格式

内联标记

  • 斜体字: 文字由*包围, 如: *这是一段斜体字*
  • 加粗: 文字由**包围, 如: **这是一段加粗文字**
  • 代码样式: 文字由``包围, 如: ``这是一段代码``

列表

要求: 列表必须总是以一个新的段落开头，也就是说，它们必须出现在一个空行之后。

  • 枚举: 以数字+./字母+./数字+)/字母+)/(数字)/(字母)等等格式均支持

    样例:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    1. numbers

    A. upper-case letters
       and it goes over many lines

       with two paragraphs and all!

    a. lower-case letters

       3. with a sub-list starting at a different number
       4. make sure the numbers are in the correct sequence though!

    I. upper-case roman numerals

    i. lower-case roman numerals

    (1) numbers again

    1) and again

  • 项目: 以-/+/*开头

    样例:

    1
    2
    3
    4
    5
    6
    7
    * a bullet point using "*"

      - a sub-list using "-"

        + yet another sub-list

      - another item

  • 定义: 与其他两个不同，定义列表由一个术语和该术语的定义组成。

    样例:

    1
    2
    3
    4
    5
    6
    7
    what
      Definition lists associate a term with a definition.

    *how*
      The term is a one-line phrase, and the definition is one or more
      paragraphs or body elements, indented relative to the term.
      Blank lines are not allowed between term and definition.

预格式化

以::作为上一段的结束语, 样例:

1
2
3
4
5
6
7
8
An example::

    Whitespace, newlines, blank lines, and all kinds of markup
      (like *this* or \this) is preserved by literal blocks.
  Lookie here, I've dropped an indentation level
  (but not far enough)

no more example
结果

另外, 如果段落仅以::开始, 内容将被忽略

1
2
3
4
::

    This is preformatted text, and the
    last "::" paragraph is removed
结果

节

要求: 下划线/上划线必须至少与标题文本一样长。保持一致，因为所有标有相同装饰风格的部分都被视为处于同一等级。

支持的字符: = - ` : ' " ~ ^ _ * + # < >

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Chapter 1 Title
===============

Section 1.1 Title
-----------------

Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~

Section 1.2 Title
-----------------

Chapter 2 Title
===============
结果

引用方式:

  • 标题中无空格的情况: 引用名为Title的标题, 可以使用Title_
  • 标题中存在空格的情况: 引用名为The article的标题, 需要使用`The article`_

文档标题/副标题

要求: 在文档开头使用唯一的装饰样式。若要指示文档副标题，请在文档标题后立即使用另一种独特的装饰样式。

1
2
3
4
5
6
7
8
9
10
11
================
 Document Title
================
----------
 Subtitle
----------

Section Title
=============

...

图片

全部图片指令参数, 见: reStructuredText Directives

1
2
3
4
5
.. image:: images/biohazard.png
   :height: 100
   :width: 200
   :scale: 50
   :alt: alternate text

Sphinx

语法格式

列表与引用

列表标记的使用最自然: 仅在段落的开头放置一个星号和一个缩进. 编号的列表也可以;也可以使用符号 # 自动加序号:

1
2
3
4
5
6
7
8
9
* 这是一个项目符号列表.
* 它有两项，
  第二项使用两行.

1. 这是个有序列表.
2. 也有两项.

#. 是个有序列表.
#. 也有两项.

列表可以嵌套，但是需跟父列表使用空行分隔

表格

支持两种表格. 一种是 网格表格, 可以自定义表格的边框. 如下:

1
2
3
4
5
6
7
8
+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

简单表格书写简单, 但有一些限制: 需要有多行，且第一列元素不能分行显示，如下:

1
2
3
4
5
6
7
8
=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

超链接

外部链接

使用 `链接文本 <http://example.com/>`_ 可以插入网页链接. 链接文本是网址，则不需要特别标记，分析器会自动发现文本里的链接或邮件地址.

可以把链接和标签分开, 如下:

1
2
3
段落里包含 `a link`_.

.. _a link: http://example.com/
内部链接

内部链接是Sphinx特定的reST角色, 查看章节 交叉索引的位置.

章节

章节的标题在双上划线符号之间（或为下划线）, 并且符号的长度不能小于文本的长度:

1
2
3
=================
This is a heading
=================

通常没有专门的符号表示标题的等级，但是对于Python 文档，可以这样认为:

  • # 及上划线表示部分
  • * 及上划线表示章节
  • =, 小章节
  • -, 子章节
  • ^, 子章节的子章节
  • ", 段落

当然也可以标记（查看 reST 文档), 定义章节的层次，但是需要注意输出格式(HTML, LaTeX)所支持的层次深度 .

指令

参见: reStructuredText 简介 — Sphinx 使用手册

Read the Docs Sphinx Theme

配置信息

Configuration — Read the Docs Sphinx Theme 1.0.0 documentation

配置项 类型 默认值 说明
collapse_navigation bool True 在导航栏是否展示[+]符号
sticky_navigation bool True 滚动页面时，使用主页内容滚动导航。
navigation_depth int 4 目录树的最大深度。将其设置为-1以允许无限深度。
includehidden bool True 指定导航是否包含隐藏的目录，即任何标记为:hidden:选项的toctree指令。
titles_only bool False 启用此选项后，导航中将不包括页面副标题。
analytics_id str None 如果指定，请参阅Google Analytics的gtag.js包含在页面中。将该值设置为google提供给您的ID（如UA-XXXXXXX或G-XXXXXXXXXX）。
analytics_anonymize_ip bool False 在Google Analytics中匿名访问者IP地址。
canonical_url str None 这将指定一个规范的URL元链接元素，告诉搜索引擎哪个URL应该被列为文档的主要URL。如果您有多个URL可以访问文档，那么这一点很重要。URL指向文档的根路径，并需要一个尾部斜杠。已在0.6.0版本后废弃
display_version bool True 是否在侧边栏显示版本信息。
logo_only bool False 仅显示徽标图像，不在侧栏顶部显示项目名称。
prev_next_buttons_location str bottom 设置“下一页”和“上一页”按钮的位置。可以是bottom、top、both或None。
style_external_links bool False 在外部链接旁边添加一个图标。
vcs_pageview_mode str blog [For Github/Gitlab]
view [For BitBucket]		 更改使用在Githuh上查看、在Gitlab上查看等时查看文件的方式。使用github或gitlab时，可以是：blob（默认）、edit或raw。在Bitbucket上，可以是：view（默认）或edit。
style_nav_header_background str #2980B9 更改导航栏中搜索区域的背景。该值可以是CSS背景属性中的任何有效值。
github_url str None 指定在Github编辑按钮引用链接地址
bitbucket_url str None 指定在BitBucket编辑按钮引用链接地址
gitlab_url str None 指定在Gitlab编辑按钮引用链接地址

链接

reStructuredText相关

reStructuredText

Quick reStructuredText

A ReStructuredText Primer

https://docutils.sourceforge.io/docs/user/rst/cheatsheet.txt

Sphinx相关

Sphinx 文档目录 — Sphinx 使用手册

使用sphinx-doc优雅的书写html和项目介绍,包含restructureText常用语法_落子无悔!的博客-CSDN博客_sphinx-doc

ReadtheDocs相关

Read the Docs tutorial — Read the Docs user documentation 8.7.0 documentation

Read the Docs Sphinx Theme — Read the Docs Sphinx Theme 1.0.0 documentation

知乎好文

Sphinx + Read the Docs 从懵逼到入门 - 知乎