入门¶
设置您的项目和开发环境¶
在一个新的目录中,创建一个名为 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.> 项目名称: 写 “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 文档.现在你可以开始 自定义它.