Use sphinx for documentation

[kragniz]

Our docs are currently a few markdown files hosted inside this repository. It'd be easier for users to find information (via search, table of contents) if this was instead rendered by sphinx (or some other documentation tool).

This could initially be hosted on readthedocs.

/kind documentation

[munnerz]

Sounds good. We need a similar thing for cert-manager too. I’m happy with Sphinx, or if we can keep it simple with something like Jekyll/Hugo then that works for me too. It’d be great if a semi reusable pattern can be invented for all of our OSS projects. My one big requirement is that they must be versioned. Ideally with a drop down menu somewhere (or similar) that lets users switch between different versions of documentation. Having a separate repo to host the docs has the added benefit of not tying docs releases to application releases, which are often slower and more involved (cherry picking PRs into release branches can become a PITA over time what with merge conflicts etc). This problem becomes worse/harder if we also use documentation artefacts as part of our test suites, so I’d be okay with not doing that, especially initially (perhaps we could have e2e suites for our documentation too, but separate from the main e2e suite for navigator).

…

On Wed, 28 Feb 2018 at 11:41, Louis Taylor ***@***.***> wrote: Our docs are currently a few markdown files hosted inside this repository. It'd be easier for users to find information (via search, table of contents) if this was instead rendered by sphinx (or some other documentation tool). This could initially be hosted on readthedocs. /area documentation — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#268>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAMbPybFuOD7OvN93yvrjcfVT0NysLPeks5tZTtQgaJpZM4SWhBl> .

[kragniz]

Readthedocs makes the documentation versioned by default (based off the git tag), so I think we're okay there.

I'd rather keep the docs in-tree, since it makes reviewing feature+associated documentation easier, and it's apparent which version of the codebase the documentation is referring to.

[kragniz]

We're now on readthedocs here: http://navigator-dbaas.readthedocs.io/en/latest/

Still to do: set up the webhook to do automated builds, maybe move to a domain like navigator.jetstack.io