3

继去年关于文档的问题之后，我现在想开始尝试基于 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 堆栈吗？

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

4

4 回答 4

6

你根本不需要在 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 服务器上。因此，没有“在 Web 服务器上安装”的操作方法、教程或资源。

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

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

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

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

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

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

于 2010-03-26T10:00:19.650 回答
3

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

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

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

于 2010-03-26T10:42:44.603 回答
1

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

于 2010-03-26T09:56:28.810 回答
1

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

于 2010-03-27T19:19:30.747 回答