开始

设置您的工程和开发环境

在新目录内，用以下内容创建名为 README.rst 的文件。

README.rst
Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

此时正是创建 Python 虚拟环境和安装所需工具的好时刻。为此，请打开命令行终端，键入 cd 和您刚创建的目录并运行如下命令：

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

备注

上述安装方法在 PyPI 包 中有更详细的描述。在本教程的其余部分，说明将假定使用Python虚拟环境。

如果您正确执行了这些说明，则应该可以使用Sphinx命令行工具。您可以通过运行以下命令进行基本验证：

(.venv) $ sphinx-build --version
sphinx-build 4.0.2

如果您看到类似的输出，则说明您走在正确的道路上！

创建文档布局

然后从命令行运行以下命令：

(.venv) $ sphinx-quickstart docs

这将向您提出一系列问题，以创建项目在 docs 文件夹内的基本目录和配置布局。要继续，请按以下方式回答每个问题：

  • > Separate source and build directories (y/n) [n]：输入“y”（不带引号），然后按 Enter。

  • > Project name：输入“Lumache”（不带引号），然后按 Enter。

  • > Author name(s)：输入“Graziella”（不带引号），然后按 Enter。

  • > Project release []：输入“0.1”（不带引号），然后按 Enter。

  • > Project language [en]：保持为空（默认值为英语），然后按 Enter。

在最后一个问题之后，您将看到包含以下内容的新 docs 目录。

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

这些文件的用途是：

build/

一个空目录（目前如此），将用于存放渲染后的文档。

make.bat 和 Makefile

方便的脚本，用于简化一些常见的 Sphinx 操作，例如渲染内容。

source/conf.py

一个包含Sphinx项目配置的Python脚本。它包含您在 sphinx-quickstart 中指定的项目名称和版本，以及一些额外的配置键。

source/index.rst

根文档，作为欢迎页面并包含“目录树”（或 toctree）的根。

多亏了这个引导步骤，您已经拥有了首次将文档渲染为HTML所需的一切。为此，请运行以下命令：

(.venv) $ sphinx-build -M html docs/source/ docs/build/

最后，在浏览器中打开 docs/build/html/index.html。您应该会看到类似这样的内容：

新创建的 Lumache 文档

新创建的 Lumache 文档

我们成功了！您使用 Sphinx 创建了您的第一个 HTML 文档。现在您可以开始 定制它。