入门

设置你的项目和开发环境

在一个新的目录中，创建一个名为 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 文件夹内为你的项目创建基本目录和配置布局。要继续进行，请按以下方式回答每个问题：

• > 分开源代码和构建目录(y/n) [n]。写入 “y”（不带引号）然后按键 Enter。

• > 项目名称：写入 “Lumache”（不带引号）然后按键 Enter。

• > 作者名称：写入 “Graziella”（不带引号）然后按键 Enter。

• > 项目发行版本 []：写入 “0.1”（不带引号）然后按键 Enter。

• > 项目语种 []：留空（默认为英语）然后按键 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 -b html docs/source/ docs/build/html

最后，在浏览器中打开 docs/build/html/index.html。你应该看到像这样的东西：

刷新创建的 Lumache 文件

我们走吧! 你用 Sphinx 创建了你的第一个 HTML 文档。现在你可以开始 定制它。