快速入门¶

设置您的项目和开发环境¶

在新目录中，创建一个名为 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 and Makefile: 方便的脚本可以简化一些常见的Sphinx操作，比如呈现内容。
source/conf.py: 保存Sphinx项目配置的一个Python脚本。它包含您为指定的项目名称和版本 sphinx-quickstart ，以及一些额外的配置密钥。
source/index.rst: 这个 root document 作为欢迎页面，并包含“目录树”的根(或 toctree )。

多亏了这个自举步骤，您已经具备了第一次将文档呈现为HTML所需的一切。为此，请运行以下命令：

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

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

我们走吧！您使用Sphinx创建了您的第一个HTML文档。现在你可以开始了 customizing it 。