De-duplicate & expand docs

[hynek]

Sorry, this is another big one 😇

I think our docs are our weakest point and the sole reason, why towncrier isn't more widely used.

There's tons of duplication, missing information and flat-out lies.

I would love to write a how-to for #128 but this needs some more big-picture work.

Here's some more notes:

• I have replaced the badges with something that is actually useful to the users. The codecov badge even was lying about 98%. We don't need a CI status badge anymore, there's a green checkmark in the GitHub UI nowadays.
• I'm sorry for the Queen, but I've killed a bunch of British English, because the rest is in American English too.
• I've switched the docs to Furo, because it's not 2010 anymore.
• I've renamed the quickstart to tutorial, to be more in line with common terms and with https://diataxis.fr which is fantastic.
• I've reordered the reference a bit, because configuration comes before customization.
• I've also split it into Narrative, Reference and Development in the hopes that someone (possibly me) fills more of the narrative. :)
• The configuration docs need a lot more polish, but I had to draw a line somewhere.
• I've added CLI reference; we should expand it.

[codecov]

Codecov Report

Base: 100.00% // Head: 100.00% // No change to project coverage 👍

Coverage data is based on head (c44d243) compared to base (0525f08).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff            @@
##             trunk      #435   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           13        13           
  Lines          600       600           
  Branches       144       144           
=========================================
  Hits           600       600           

Impacted Files	Coverage Δ
src/towncrier/_settings/fragment_types.py	100.00% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[adiroiban]

Docs at https://towncrier--435.org.readthedocs.build/en/435/ are awesome

I will not have time soon to look into the details of this, but I think is best to have this merged.

If anything needs improvements we can create smaller PRs for that change and discuss it.

---

I agree that the current docs are a mess, so this looks so much better.

Thanks for https://diataxis.fr/
I wasn't aware of it.

Again
Awesome work!

[adiroiban]

I think this ok for now.

In the future maybe we can use something like https://pypi.org/project/sphinx-click/ to automatically keep the reference up to date.

[hynek]

Yes and no…I think the reference docs should do more than parroting --help output. Maybe some kind of combination idk.

[adiroiban]

I agree that in the docs we can do more than copy/pasting --help

But we should make sure the --help output is useful and can serve as documentation.

Having all the --help output in the docs can serve as a base-line.

But if there is anyting important, I would prefer to have it inside the --help output and not keep it only for the HTML docs :)

I use the --help command more often than checking the HTML / narrative docs for a project.

[hynek]

Thanks for the quick review Adi! Hope this lays the ground for better docs in the future!