使用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 反映了新的更改！

以其他格式构建文档

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

(.venv) $ make epub

之后，您将在 docs/build/epub/ 下看到与电子书对应的文件。您可以使用兼容 EPUB 的电子书阅读器（如 Calibre）打开 Lumache.epub，或者在网页浏览器中预览 index.xhtml。

注意

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

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

docs/source/conf.py
# EPUB options
epub_show_urls = 'footnote'

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

注意

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