PyCharm教程：如何用Python构建一个Sphinx 站。

本系列教程主要是做一个有依赖的项目和虚拟环境，然后做一个简单的Sphinx 站。

本系列教程主要是做一个有依赖的项目和虚拟环境，然后做一个简单的Sphinx 站。

Sphinx可以被添加到现有的Python应用程序或库中，以提供文档。但它也可以作为项目本身使用–比如说，一个 站。在本教程的步骤中，我们用Sphinx启动一个新的 站，作为一个新的Python项目。

设想

本教程将模拟为一家名为 “Schlockchain “的虚构公司建立 站。该公司显然有很多想要进行的营销活动。它也有一些代码和–显然–它想展示的专利。风险资本家想要一个 站，创始人并不是真正的技术人员，所以他们想使用Markdown。

新项目

首先，让我们创建一个新目录并将其更改为：

$ mkdir schlockchain$ cd schlockchain

注意：我们在本教程中使用 macOS/Linux/WSL 命令 shell 语法。

Python 推荐项目使用虚拟环境进行隔离。Real Python 有一个关于虚拟环境的很好的入门读物，包括为什么、什么、以及如何。让我们建立一个新的虚拟环境，存储在我们项目的 .venv 目录中。然后我们将 “激活 “它，这将改变我们的命令路径，使之首先在这个虚拟环境的 bin 中查找。

$ python3 -m venv .venv$ source .venv/bin/activate

pip是 Python 的软件包安装程序。更新您的pip. 请注意，在下面，由于source上面的行，我们的 shell 正在使用python3虚拟环境目录：

$ pip install --upgrade pip

我们新的空白 Python 项目现在已准备好安装 Sphinx。

安装 Sphinx

sphinx

我们现在可以使用激活的 shellpip来安装我们的依赖项：

$ pip install -r requirements.txt

Sphinx 本身有许多依赖项，因此获取所有包可能需要一段时间。完成后，让我们确认 Sphinx 已安装并在我们的路径上：

$ which sphinx-quickstart[some path prefix].venv/bin/sphinx-quickstart

Sphinx 有许多命令（用 Python 实现）。它们被添加到您的虚拟环境bin目录中。如果你看到sphinx-quickstart，你的状态很好。

制作一个Sphinx 站

Sphinx有一个 站生成器的命令，叫做sphinx-quickstart，现在在你的虚拟环境的bin目录中。

让我们运行它并回答一些问题，接受大多数默认值（注意…是隐藏我的目录路径）：

$ sphinx-quickstartWelcome to the Sphinx 3.2.1 quickstart utility.Please enter values for the following settings (just press Enter toaccept a default value, if one is given in brackets).Selected root path: .You have two options for placing the build directory for Sphinx output.Either, you use a directory "_build" within the root path, or you separate"source" and "build" directories within the root path.> Separate source and build directories (y/n) [n]: The project name will occur in several places in the built documentation.> Project name: Schlockchain> Author name(s): Paul Everitt <pauleveritt@me.com>> Project release []: If the documents are to be written in a language other than English,you can select a language here by its language code. Sphinx will thentranslate text that it generates into that language.For a list of supported codes, seehttps://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.> Project language [en]: Creating file /.../schlockchain/conf.py.Creating file /.../schlockchain/index.rst.Creating file /.../schlockchain/Makefile.Creating file /.../schlockchain/make.bat.Finished: An initial directory structure has been created.You should now populate your master file /.../schlockchain/index.rst and create other documentationsource files. Use the Makefile to build the docs, like so:   make builderwhere "builder" is one of the supported builders, e.g. html, latex or linkcheck.

下面是我们的目录在运行后的样子：

(.venv) schlockchain pauleveritt$ lsMakefile        _templates      make.bat_build          conf.py         requirements.txt_static         index.rst

关于其中一些目录项：

• conf.py是Sphinx配置文件

• index.rst 是我们 站顶部的“主页”或文档

• Makefile（make.bat适用于 Windows）是一个简单的命令运行程序

• _build（生成的文件）、_static（自定义站点资产）和_templates（自定义模板）存在空目录。

注意：如果您使用的是 PyCharm 等 IDE，请将_build目录标记为已忽略。

好了这就是今天的内容了，下一节将继续讲解如何构建 站。不要忘了在评论与我们分享您的想法和建议，作为IntelliJ IDEA正版合作商，我们推出”软件国产化服务季”活动（点击查看详情）！现PyCharm正版授权在线订购最高立减3000元！低至1333！还有多种授权方式供你选择。

====================================================

想要了解或购买PyCharm正版授权的朋友，欢迎咨询官方客服

JetBrain技术交流群现已开通，QQ搜索群 “786598704”或者扫描下方二维码即可加入

标签：