入门¶
设置你的项目和开发环境¶
在一个新目录中，创建一个名为 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。> 项目 语言 [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 文档¶
瞧！你利用 Sphinx 创建了第一个 HTML 文档。现在，你可以开始 自定义它。