munnerz
commented
6 years ago 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 notifications@github.com 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 https://github.com/jetstack/navigator/issues/268, or mute the thread https://github.com/notifications/unsubscribe-auth/AAMbPybFuOD7OvN93yvrjcfVT0NysLPeks5tZTtQgaJpZM4SWhBl .
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