How to host a privately owned documentation with ReadTheDocs or Sphinx

Question

I am totally new to this thing. Spent a whole day trying to figure out the "most commonly used" approach. What I want to implement is something like readthedocs.org, but for a private customer (and proprietary project).

Almost all of the FAQs, blog posts, howtos, etc, are describing how to host (publish) documentation either with GitHub pages, either with readthedocs.org (.com)

I've tried to use Sphinx (NB: NOT a "Sphinx Search") locally, and I could quite easily build a sample demo docs, but I don't exactly understand how to host a "searchable" solution, like the one it works on http://www.sphinx-doc.org (seems like it uses readthedocs.org as a search backend, though).

I've tried to deploy readthedocs.org locally, but:

1. The "search" doesn't work (nobody listens on 127.0.0.1:9200).
2. I was unable to build any documentation (Version not found or Project not found).
3. I was unable to add project from my private repository (ssh:)

(NB: I was trying it on Windows, and that might explain items 1-2, but not 3, I believe.)

So far it feels like I've run out of ideas..

Any advice will be highly appreciated !

Jessie

Answer 1

The only thing you need to host sphinx documentation is a static file server (the search works without a back end, see my answer here.

That said, using a private readthedocs server is probably over-engineering. Just deploy the files to a static file server and point the base URL (e.g. docs.myapp.com) to the index.html file.

You can automate the deployment with git hooks.

For the sake of completeness: I am sure it is possible to get a local readthedocs server to build your project. But readthedocs is explicitly not designed for On Premise deployments and you might find it hard to get professional support. I was involved in a scenario where the Dev Ops team decided it's way easier to automate the deployment using their usual set of tools after we struggled with build/performance issues of our local readthedocs instance.

Inhospitality

I've found that adding a 'make publish' target to the sphinx-generated Makefile (which uses rsync and depends on the dirhtml target) is a simple and clean solution, which lets me control when the documentation gets updated. Generating docs for every commit seemed to be fairly wasteful (and resulted in bad doc versions getting pushed) – Twohanded

Answer 2

If you want to host static documentation you can do this by setting up a static file server like nginx. Just this file in /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;
    }
}

We built a simple tool around this concept to selfhost documentation for multiple projects and version them:

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

Registrar