使用 Sphinx 文档您的项目的第一步¶
构建您的 HTML 文档¶
由 sphinx-quickstart
创建的 index.rst
文件已经包含了一些内容,并且它被渲染为您的 HTML 文档的首页。它使用 reStructuredText 编写,这是一种强大的标记语言。
按如下方式修改文件
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 兼容的电子书查看器(例如 Calibre)打开 Lumache.epub
,或者在 Web 浏览器中预览 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.builders.latex.LaTeXBuilder
文档中所述。尽管这完全可行,但此类安装通常很大,并且通常 LaTeX 在某些情况下需要仔细配置,因此本教程不涉及 PDF 生成。