使用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 警告 （可用的 directives 之一）

现在，为了用新内容渲染它，您可以像以前一样使用 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 或用网络浏览器预览 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生成超出了本教程的范围。