入门¶

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

在一个新目录中，创建一个名为 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 文件夹内。要继续，请按如下方式回答每个问题

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

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

这些文件的目的是

build/: 一个空目录（目前），将保存渲染后的文档。
make.bat 和 Makefile: 简化一些常见的 Sphinx 操作（例如渲染内容）的便捷脚本。
source/conf.py: 一个 Python 脚本，用于保存 Sphinx 项目的配置。它包含您在 sphinx-quickstart 中指定的项目名称和版本，以及一些额外的配置键。
source/index.rst: 项目的根文档，作为欢迎页面，并包含“目录树”（或 toctree）的根。

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

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

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

就这样！您使用 Sphinx 创建了您的第一个 HTML 文档。现在您可以开始自定义它了。