Docs Rewrite

[Rowlando13]

The docs are good, but not great. Click is an awesome API so it should have really great docs.

Part I Big Swags

• Take big swags at reorganization.
• Rewrite sections to fit into Diataxis sections.
• Include more examples.
• Make the text more skimmable
• Rewrite to make more concise and precise
• Written to an person proficient in python, but not the command line.
• Status: ~50 percent.

Part II Nice for Long Term

• Reorganize along diataxis sections and rewrite as necessary
  • reference
  • guides
  • explanation
  • tutorial
• fully type hinted
• note on landing page about type hints in docs
• note on landing page about docs organization
• Make landing page toc tree more compact
• Not comprehensive, but the holes are obvious for future contributor work
• Nice to have:
  • rewrite in myst