如何使用ReadTheDocs或Sphinx托管私有文档

Question

我对这件事情全新.花了一整天试图找出"最常用"的方法.我想要实现的是像readthedocs.org,但对于私人客户(和专有项目)

几乎所有的常见问题解答,博客文章,howtos等都在描述如何使用GitHub页面使用主机(发布)文档,或者使用readthedocs.org(.com)

我试图在本地使用Sphinx(NB:不是 "Sphinx搜索"),我可以很容易地构建一个示例演示文档,但我并不完全理解如何托管"可搜索"的解决方案,就像它一样适用于http://www.sphinx-doc.org(似乎它使用readthedocs.org作为搜索后端)

我试图在本地部署readthedocs.org,但是

1. "搜索"不起作用(没人监听127.0.0.1:9200)
2. 我无法构建任何文档(找不到版本或找不到项目)
3. 我无法从我的私人存储库添加项目(ssh :)

(注意:我在Windows上尝试它,这可能解释1-2项,但不是3,我相信)

到目前为止感觉我的想法已经用完了......

任何建议将受到高度赞赏!

Answer 1

您需要托管sphinx文档的唯一方法是静态文件服务器(搜索工作没有后端,请参阅我的答案.

也就是说,使用私有readthedocs服务器可能过度工程.只需将文件部署到静态文件服务器,并将基本URL(例如docs.myapp.com)指向该index.html文件.

您可以使用git hooks自动部署.

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

Answer 2

如果你想托管静态文档，你可以通过设置一个像 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/randombenj/docat