使用 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 的电子书阅读器打开 Lumache.epub，如 Calibre，或在网络浏览器上预览 index.xhtml。

备注

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

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

# EPUB options
epub_show_urls = 'footnote'

有了这个配置值，再次运行 make epub 后，你会注意到 URL 现在以脚注的形式出现，这就避免了文本的混乱。真棒！继续阅读探索 自定义 Sphinx 的其他方法。

备注

使用 Sphinx 生成 PDF 可以运行 make latexpdf，前提是系统有一个工作的 LaTeX 安装，在 sphinx.builder.latex.LaTeXBuilder 的文档中解释。虽然这是完全可行的，但这样的安装往往很大，而且一般来说，LaTeX 在某些情况下需要仔细配置，所以 PDF 生成不在本教程的范围内。