在 App Engine 上安装 Sphinx - 可能吗？

Question

继续我去年关于文档的问题，我现在想开始并尝试基于 Python 的Sphinx来整理我一直在研究的 PHP CMS 的开发人员文档。

我不想在我的工作站上本地设置 Python，而是希望从一开始就在可公开访问的 Web 服务器上运行它。 我有权在 LAMP 堆栈上运行的所有网络托管包，我不愿意购买基于 Python 的托管。 我对 Google App Engine 非常感兴趣，他们提供的免费配额对我来说是一百倍，即使没有，他们的定价看起来也很合理。

现在我对 Python 的了解为零——让 Sphinx 工作将是我第一次接触它——而且时间很少。 据我了解，App Engine 提供的平台和 Python 库与标准 Python 库非常兼容，但不完全相同。

所以我的问题是：

• Sphinx 可以在 App Engine 上运行吗？

• 在 App Engine 上安装 Sphinx 是否像将它安装在普通 Python 安装之上一样简单？ 或者 App Engine 的环境是否需要调整我目前的 Python 水平无法在合理时间内执行的源代码？

• 我应该先在本地服务器上安装 Sphinx 而不是“普通”Python 堆栈吗？

• 有没有人知道任何有用的操作方法、教程或其他资源？

Answer 1

您根本不需要在 GAE 上安装 Sphinx。

您使用 Sphinx 创建静态 HTML、CSS 和 JS 的目录。 完成此步骤后，您只需上传 Sphinx 的输出 —— 完整的。

Sphinx 的输出（HTML、CSS 和 JS）只需从一处提供。 您将文档从创建位置上传到 GAE 作为静态文件并提供它们。 完毕。

Sphinx 根本没有“安装在 Web 服务器上”方面。 Sphinx 不是 Web 应用程序； 它不会在您的 Web 服务器上运行。 您可以在开发中简单地运行它以将文档发布为 HTML、LaTeX 或其他格式。 一旦您创建了静态 HTML 文件，您就不再需要 Sphinx 的任何部分。

Sphinx 可以在 App Engine 上运行吗？

我想它可以，但你永远不需要。

在 App Engine 上安装 Sphinx 是否像...

没关系，因为你没有安装它。 您将它安装在您的工作站上并在您的工作站上使用它。

我应该先在本地服务器上安装 Sphinx 而不是“普通”Python 堆栈吗？

不要安装在服务器上。 将其安装在您的工作站上。

有没有人知道任何有用的操作方法、教程或其他资源？

如果“这个”是指“安装在网络服务器上”，那么答案是“否”。 没有将它安装在 Web 服务器上。 因此，没有关于“在 Web 服务器上安装”的操作方法、教程或资源。

如果“这个”是指“使用 Sphinx 创建文档”，那么答案是“ https://www.sphinx-doc.org 有什么问题？他们缺少什么？

---

我希望 Sphinx 的“引擎”将输入（由 reST 文件组成）转换为 HTML/CSS/JS，以便从任何地方访问，使我（和可能的其他贡献者）独立于特定工作站。

Sphinx 就像一个编译器。 每个人的工作站上都​​有自己的副本。 他们下载文档源、进行更改、提交源更改并上传生成的文档。

从同一个地方提供生成的文档。

正确的。 在您下载源代码、进行更改、重新生成文档并提交更改后，您上传生成的文档，以便从一个地方提供——而且只有一个地方。

Sphinx 是一个编译器。 它不是“网络引擎”。 它是一个简单的编译器，可以将您的文档简单地编译为 HTML，以便提供服务。

Answer 2

有趣的项目！ 您将遇到的主要问题是文件系统访问：App Engine 上的文件系统是只读的，并且基于查看源代码，Sphinx 是相当硬编码的以使用文件系统进行输出。 它还希望从本地文件系统中读取配置文件和输入文件，这使得为与应用程序捆绑的项目以外的任何内容构建文档变得棘手。

它可以解决这个问题，但它需要编写使用App Engine数据存储简单的虚拟文件系统，并且使用的Monkeypatching ，使其与普通的Python文件接口工作。 这对于“Python 新手”项目来说相当先进！

如果您正在考虑允许用户上传要记录的项目，您可能需要考虑的另一件事是：Sphinx 配置文件使用 Python 编写，因此执行它可能很危险 - 用户可能会使用恶意配置文件对您的应用程序做一些令人讨厌的事情！

Answer 3

通过dev_appserver本地部署和通过appcfg远程部署之间的区别 - 根据我的经验 - 仅限于我执行的两个命令中的哪一个。 也就是说，我没有使用 Sphinx 的经验。

Answer 4

Sphinx 编译文档，在网络服务器上运行它与在网络服务器上运行 gcc 一样有意义。