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: 100 percent.

Part II Nice for Long Term

• Reorganize along diataxis sections and rewrite as necessary
  • reference
  • guides
  • explanation
  • tutorial
• rewrite in myst if possible
• note on landing page about type hints in docs
• Not comprehensive, but the holes are obvious for future contributor work
• Nice to have:
  • fully type hinted
• Status: 10 percent.

Part I PRs

• Reduce click contrib #2515
• Separate out virtualenv to its own sections #2551
• Make examples section nicer. #2580
• Clean up parameters intro. #2585
• Break up arguments section #2586
• Rewrite help page section. #2821
• Rewrite first half of options docs #2825
• Rewrite Commands and Groups docs. #2838
• Rewrite second half of options docs #2848

Part II PRs

• Organize docs along diatxis categories. #2898
• Rewrite testing docs and move from rst to myst #2857
• Make faqs section. Add the first question about windows shell expansion. #2927
• Make distinct sections for advanced patterns and extending click. #2925
• Convert options docs to md. #2924