使用 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.

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

# EPUB options
epub_show_urls = 'footnote'

使用这个配置值,并且在再次运行 make epub 之后,你会注意到URL现在作为脚注出现,这避免了文字的杂乱.太棒了!继续阅读以探索 其他自定义 Sphinx 的方法.

备注

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