28

我对这件事完全陌生。花了一整天试图找出“最常用”的方法。我想要实现的是类似于 readthedocs.org 的东西，但是对于私人客户（和专有项目）。

几乎所有常见问题解答、博客文章、操作指南等都在描述如何使用 GitHub 页面或使用 readthedocs.org (.com) 托管（发布）文档

我尝试在本地使用 Sphinx（注意：不是“Sphinx 搜索”），我可以很容易地构建一个示例演示文档，但我并不完全了解如何托管一个“可搜索”解决方案，比如它适用于http://www.sphinx-doc.org（不过，它似乎使用 readthedocs.org 作为搜索后端）。

我尝试在本地部署 readthedocs.org，但是：

  1. “搜索”不起作用（没有人在 127.0.0.1:9200 上收听）。
  2. 我无法构建任何文档（未找到版本或未找到项目）。
  3. 我无法从我的私人存储库 (ssh:) 添加项目

（注意：我在 Windows 上尝试过，这可能解释了第 1-2 项，但不是第 3 项，我相信。）

到目前为止，感觉就像我已经没有想法了..

任何建议将不胜感激！

4

2 回答 2

20

托管 sphinx 文档所需的唯一东西是静态文件服务器（搜索无需后端即可工作，请参阅我的答案here。

也就是说，使用私有的 readthedocs 服务器可能是过度设计的。只需将文件部署到静态文件服务器并将基本 URL（例如docs.myapp.com）指向index.html文件即可。

您可以使用git hooks自动化部署。

为了完整起见：我确信可以使用本地 readthedocs 服务器来构建您的项目。但是 readthedocs 显然不是为 On Premise 部署而设计的，您可能会发现很难获得专业支持。我参与了一个场景，在我们遇到本地 readthedocs 实例的构建/性能问题后，Dev Ops 团队决定使用他们常用的工具集来自动化部署更容易。

于 2016-07-10T17:55:21.177 回答
5

如果你想托管静态文档，你可以通过设置像 nginx 这样的静态文件服务器来做到这一点。只是 /etc/nginx/sites-available/default 中的这个文件：

server {
    listen 80 default_server;

    index index.html index.htm index.nginx-debian.html;

    server_name _;

    location /doc/your-docs {
        root /path/to/docs;
    }
}

我们围绕这个概念构建了一个简单的工具来为多个项目自托管文档并对其进行版本控制：

https://github.com/docat-org/docat

于 2019-11-13T09:32:09.740 回答