Cert-manager: readthedocs documentation site

[munnerz]

In order to improve readability and consistency of our documentation, I've gotten started putting together a rewrite/restructure of our docs into rst using Sphinx.

The plan is to then publish these docs to readthedocs, who can handle versioning etc. for us too 😄

I have not published my updates publicly yet, but will do soon and will update this issue accordingly. I'm roughly planning to split into a few categories:

• Overview/about (akin to the current root README)

• Getting started (covers deployment instructions)

  • Deploy with Helm
  • Configuring helm (link out)
  • Installing chart
  • Setting different options on chart (e.g. extraArgs)
  • Deploy without Helm
  • Where to find static manifests
  • How to apply them
  • Modifying them/adding flags
  • Configuring your first issuer (provide some background on what this step is & why it's required, and link out to 'fuller' documentation in the tutorials section)

• Tutorials (full guides on how to do a particular thing with cert-manager. They require cert-manager to already be deployed in order to follow).

  • ACME
  • Migrating from kube-lego
  • Securing nginx-ingress with Let's Encrypt
  • CA
  • Deploying your own internal CA and issuing Certificates as Secrets

• Reference - a pretty 'dry' doc, going into a lot of technical detail

  • Certificates - explain all the different options, how things are defaults, behaviour of different fields. Provide examples too for different controllers, but don't write a tutorial on how to configure everything (that's for the tutorials section)
  • Issuers - explain all different dns providers for ACME, explain all different issuer types, nuances of different fields etc.
  • ClusterIssuers - brief, explain difference between Issuer & ClusterIssuer and link to Issuer doc for full config details
  • ingress-shim - detail what it is, how it works and how to configure it

• Development (development documentation)

  • Building your own images
  • Running e2e tests
  • Development environment

I've been trying to read up on good documentation structure (it's actually really difficult!). If anyone has any feedback on this structure, or has suggestions for something better or just generally any thoughts, I'd greatly appreciate it!

/cc @ahmetb @whereisaaron @kragniz

[chiquitawow]

I'm about to go through the steps of securing a nginx-ingress with Let's Encrypt. I would be glad to go over the steps and give some feedback if needed. :)

[kragniz]

@munnerz this sounds like a good plan. Your current structure looks sensible and pretty comprehensive