bpo-27752: improve documentation of csv.Dialect

[jdevries3133]

Note that all content changes are in the first commit. The second commit is 100% formatting of the rst file. There are also some very minor proofreading corrections in the final commit.

I'm very open to feedback on this; please let me know if there are any bits in here that you feel could be communicated better!

https://bugs.python.org/issue27752

[iritkatriel]

Note that all content changes are in the first commit. The second commit is 100% formatting of the rst file. There are also some very minor proofreading corrections in the final commit.

The formatting (whitespace?) changes are unlikely to be approved. You should limit this PR to the content change you are making (possibly fix typos in other places).

The PR will be squashed into one commit, so the diff will be huge and hide the actual change. Sweeping whitespace-type changes are not going to be accepted in a separate PR either because they spam the commit log and the "blame" outputs.

[jdevries3133]

@iritkatriel Ok, those changes have been reverted.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[jdevries3133]

Don't mind me; just talking to myself. When this was marked stale,I opened it up and saw these issues. I will fix them soon, but don't want anyone to waste their time reviewing in the interim.

[iritkatriel]

Don't mind me; just talking to myself. When this was marked stale,I opened it up and saw these issues. I will fix them soon, but don't want anyone to waste their time reviewing in the interim.

You can mark the PR as draft and then people won't review it until you say it's ready.

[jdevries3133]

You can mark the PR as draft and then people won't review it until you say it's ready.

@iritkatriel Yes, well the other factor here is that I was reading the diff just before bed and wanted to leave myself the notes as breadcrumbs, too!

Anyway, this PR is ready for another review, I think it is ready to go. The diff is much smaller as I got rid of all whitespace changes, plus a lot of pedantic changes that I can now see were unnecessary. A summary of the changes now are:

• fix mechanics in two places: change "the dialect" to "dialects" when speaking about dialect classes, in general
• revise and expand the paragraph of documentation for the Dialect class to make it more descriptive and less technical-jargon dense
• create hyperlink by changing change "dialect" to "class:Dialect" where appropriate

[miss-islington]

Thanks @jdevries3133 for the PR, and @ambv for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-bot]

GH-27643 is a backport of this pull request to the 3.10 branch.

[bedevere-bot]

GH-27644 is a backport of this pull request to the 3.9 branch.