使用 Python 工具构建网站

并非每个网站都是博客，其主要功能是文章列表，每篇文章都有特定的时间戳来表示其“新鲜度”。有时，您只想拥有一个*网站*。

也许您是一位业余（或专业！）厨师，想要展示您的食谱。也许您是一位诗人，想要一个网站来发表您的所有诗歌。也许您有强烈的观点，想要一个地方来存储您的咆哮，每一个都处于永恒的完美状态。这就是 Sphinx 的用武之地。

构建 Sphinx 网站

本操作指南将使用一个虚构的创业公司需要构建网站的例子。 在另一个宇宙中，乘法和否定在计算上非常繁重。 可以在您的本地笔记本电脑上进行计算，但这需要很长时间。 进入云和您的虚构公司 Calculate Solutions。 它提供计算即服务，这肯定会颠覆计算行业。

工程师们正在努力构建一个最小可行产品，而营销部门需要创建一个有吸引力的网站来展示该解决方案。 由于没有可用的工程资源，因为所有资源都致力于解决乘法和否定问题，并且预算很少，您该怎么办？

故事从本地 Git 存储库开始，以便版本控制该网站。

像所有好的 Git 存储库一样，这个存储库以 .gitignore 开头，它告诉 Git 忽略其中列出的文件或目录。 这是一个简单、不起眼的 .gitignore

/build

我将在下面解释为什么您要将此目录添加到 .gitignore 文件中。

接下来，是时候让文案人员编写营销文案了。 在 doc/index.rst 中，他们编写了格式正确的 reStructuredText

Calculate Solutions
-------------------

Learn how to add, subtract, multiply, and divide!

.. toctree::

    multiplication
    negation

标点符号和 toctree 的使用使我们可以创建我们打算构建的子页面的目录。 接下来，我们可以将有关 Calculate Solutions 的具体产品的更多详细信息放在 doc/multiplication.rst 和 doc/negation.rst 中。

然后添加一个简短的文件 doc/conf.py，其中包含重要的元数据

master_doc = 'index'
project = "Calculate.Solutions"
copyright = '2020, Calculate Solutions, Inc.'
author = 'Calculate Solutions, Inc.'
version = release = ''

并将版本和发行版设置为空字符串。 Sphinx 的最初目的是记录软件，这是一种版本和发行版标签很重要的用例，但它们对 Calculate Solutions 的网站没有用处。

最后，确保您可以在本地构建文档并查看其外观是否良好。 为此，请使用 tox，一个方便的自动化和测试库。

将以下 tox 配置文件保存到 tox.ini

[tox]
envlist = website
toxworkdir = {toxinidir}/build/tox
skipsdist = True

[testenv:website]
basepython = python3.7
deps =
    sphinx
changedir = doc
commands =
    sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html

tox 配置分为两部分：一部分是常规配置，另一部分设置特定的“测试环境”。 常规配置设置测试环境列表； 在这里，您只有一个，即在本地构建您的网站的环境。 您还必须配置工作目录。 这很有用，因为默认情况下，tox 会将其输出放入 .tox 目录中。 有时很难从 GUI 程序（如 Web 浏览器）打开此类“隐藏”目录。 因此，请将其放在 build 下，您在 .gitignore 中小心忽略的目录。

默认情况下，tox 假定您正在测试 Python 包。 由于您不是，请告诉它 skipsdist。

在环境配置中，明确指定要使用的 Python 解释器。 Tox 有时会尝试从环境名称中推断出这一点，但在这种情况下，检测不起作用。 确保您在此处设置的版本可从您的路径获得。

从那里，告诉 tox 在它为此运行创建的虚拟环境中安装 Sphinx，然后更改到您的 doc 目录，您将配置和营销文案放在其中，并运行构建网站的 sphinx 命令。

现在您可以简单地运行

$ tox

成功运行后，在浏览器中打开 build/docs/tmp/html/index.html 以查看其外观是否良好。

发布您的网站

现在您需要将您的网站从本地开发中转移到世界各地！ 您可以创建一个 CI/CD 管道，它可以自动刷新并推送它，设置负载均衡器，并设置 HTTPS 证书，但这似乎需要大量工作。

输入 Read The Docs。 Read the Docs 是一个免费网站，可以自动发布基于 Sphinx 的文档，并且它全部由开源软件构建，由 非常周到的维护者 构建。

创建或登录您的 Read The Docs 帐户后，转到导入屏幕。

您可能需要刷新您的帐户或项目列表，但最终您应该在选项列表中看到您的项目。

您不需要任何高级选项，因此接受默认设置并继续。

单击“构建”按钮启动构建，您的第一个文档构建应该开始

第一次构建应该添加 Webhook 以将您的 Git 存储库连接到发布到 Read the Docs。 如果您遇到问题，则有 丰富的文档介绍如何手动添加它。

构建完成后，您的网站就启动了！

但是，您希望它位于您的*真实域名* calculate.solutions 上。

为此，请使用 Read The Docs 上的自定义域名功能。

最后，您的网站已准备好公开发布。

虽然您是一家颠覆性的创业公司，但您仍然努力支持开源服务，因此请将您的帐户升级到黄金级别，并将无广告选项应用于您的网站。

这也使您的网站看起来更专业！

无需运营的网站

如果您需要一个网站来存放您的食谱、诗歌、咆哮或计算即服务创业公司，Sphinx 和 Read The Docs 是一种简单的方法，无需运营即可构建网站。 将该站点与最少的 tox 和 Sphinx 配置相结合，您将拥有一个无需自己运行的可扩展基础设施。 成功！