使用Sphinx记录项目的第一步

构建您的HTML文档

这个 index.rst 提交该文件 sphinx-quickstart Created已经有了一些内容，并且它被呈现为您的HTML文档的首页。它是用一种功能强大的标记语言reStruredText编写的。

按如下方式修改文件：

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.

它展示了reStrutiredText语法的几个功能，包括：

• 一个 section header 使用 === 对于下划线，

• 以下两个示例 内联标记 ： **strong emphasis** (通常为粗体)和 *emphasis* (通常为斜体)，

• 一个 inline external link ，

• and a note admonition (one of the available directives)

现在，要使用新内容呈现它，您可以使用 sphinx-build 命令，或按如下方式利用方便脚本：

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

运行此命令后，您将看到 index.html 反映了新的变化！

以其他格式构建您的文档

除了HTML之外，Sphinx还支持多种格式，包括PDF、EPUB and more 。例如，若要以EPUB格式生成文档，请从 docs 目录：

(.venv) $ make epub

之后，您将在以下位置看到与该电子书对应的文件 docs/build/epub/ 。您可以打开 Lumache.epub 使用与EPUB兼容的电子书查看器，如 Calibre ，或预览 index.xhtml 在网络浏览器上。

备注

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

每种输出格式都有一些可以调整的特定配置选项， including EPUB 。例如，缺省值 epub_show_urls 是 inline 这意味着，默认情况下，URL显示在相应链接后面的括号中。您可以通过在您的 conf.py ：

# EPUB options
epub_show_urls = 'footnote'

使用此配置值，并在运行 make epub 同样，您会注意到URL现在显示为脚注，这避免了文本混乱。甜!继续阅读以探索 other ways to customize Sphinx 。

备注

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