gh-105096: Reformat wave documentation

[vstinner]

Add ".. class::" markups in the wave documentation.

• Reformat also wave.py (minor PEP 8 changes).
• Remove redundant "import struct": it's already imported at top level.

• Issue: wave: Deprecate getmark(), setmark() and getmarkers() methods #105096

---

📚 Documentation preview 📚: https://cpython-previews--105136.org.readthedocs.build/

[vstinner]

@hugovk: I wrote this doc change to help me fixing PR #105098 doc warnings :-)

[vstinner]

The wave.py file only uses "WAVE" name, whereas the doc only uses "WAV" name. The Wikipedia article is called "WAV" and says that the format is called "WAVE". The Python module is called "wave". I'm confused :-) https://en.wikipedia.org/wiki/WAV

[hugovk]

Nice, just three Sphinx warnings left:

Warning: py:meth reference target not found: close
Warning: py:meth reference target not found: get*
Warning: py:meth reference target not found: set*

For the first one, I think we can just add an exclamation mark, because I don't think we know which close it is in this context?

For the last two, we can either add an exclamation mark (for example, :meth:!get*) or list the actual methods, but there's quite a lot, so !` is good.

When there's no longer any warnings in wave.rst, we can remove it from Doc/tools/.nitignore, then the CI won't allow new warnings back into wave.rst.

[hugovk]

Oh and let's backport this to 3.11, I'll add the labels.

[vstinner]

Nice, just three Sphinx warnings left:

Interesting. I tried to fix them.

For the last two, we can either add an exclamation mark

I used the lazy fix: I removed :meth: markup and use preformatted text instead.

I will wait for your new review. Tell me if you want further changes. The new code looks good: https://cpython-previews--105136.org.readthedocs.build/en/105136/library/wave.html#wave-read-objects

I'm not excited by wave.Wave_write documentation, but I was too lazy to come up with something better.

[hugovk]

Thanks, a definite improvement!

[miss-islington]

Thanks @vstinner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

[miss-islington]

Sorry, @vstinner, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 85e5d03163cac106ac8ec142ef03f1349a48948b 3.12

[miss-islington]

Sorry @vstinner, I had trouble checking out the 3.11 backport branch.
Please retry by removing and re-adding the "needs backport to 3.11" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 85e5d03163cac106ac8ec142ef03f1349a48948b 3.11

[bedevere-bot]

GH-105138 is a backport of this pull request to the 3.12 branch.