使用 Sphinx 记录你的项目的首要步骤

构建你的 HTML 文档

sphinx-quickstart 创建的 index.rst 文件已经包含了一些内容,它会被渲染成 HTML 文档的首页。它是用 reStructuredText 编写的,一种强大的标记语言。

按如下方式修改文件

docs/source/index.rst
Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

这展示了 reStructuredText 语法的几个特性,包括

  • 使用 === 作为下划线的章节标题

  • 内联标记 的两个例子:**strong emphasis** (通常为粗体) 和 *emphasis* (通常为斜体),

  • 一个内联外部链接

  • 以及一个 note 提示 (可用的 指令 之一)

现在要用新内容渲染它,你可以像以前一样使用 sphinx-build 命令,或者利用如下的便捷脚本

(.venv) $ cd docs
(.venv) $ make html

运行此命令后,你将看到 index.html 反映了新的更改!

构建其他格式的文档

除了 HTML 之外,Sphinx 还支持多种格式,包括 PDF、EPUB、以及更多。例如,要以 EPUB 格式构建文档,请从 docs 目录运行此命令

(.venv) $ make epub

之后,你将在 docs/build/epub/ 下看到与电子书对应的文件。你可以使用兼容 EPUB 的电子书阅读器(如 Calibre)打开 Lumache.epub,或者在 Web 浏览器上预览 index.xhtml

注意

要快速显示可能的输出格式的完整列表,以及一些额外的有用命令,你可以运行 make help

每种输出格式都有一些特定的配置选项可以调整,包括 EPUB。例如,epub_show_urls 的默认值为 inline,这意味着默认情况下,URL 会显示在相应链接之后,用括号括起来。你可以通过在 conf.py 的末尾添加以下代码来更改此行为

# EPUB options
epub_show_urls = 'footnote'

使用此配置值,并在再次运行 make epub 后,你将注意到 URL 现在以脚注形式出现,这避免了文本的混乱。真棒!继续阅读以探索自定义 Sphinx 的其他方法

注意

可以使用 make latexpdf 运行来生成 PDF,前提是系统已安装可用的 LaTeX,如 sphinx.builders.latex.LaTeXBuilder 的文档中所述。虽然这完全可行,但此类安装通常很大,并且在某些情况下,LaTeX 通常需要仔细配置,因此 PDF 生成不在本教程的范围内。