Fix deprecations as warnings

[matteobachetti]

Resolve #735

enable_deprecations_as_warnings does not exist anymore in astropy. The recommended way is to now let all warnings be errors, unless the ones that are ignored or caught properly.

This PR eliminates the call to enable_deprecations_as_warnings, and contextually, changes the code to be much more robust in catching harmful warnings.

My PR is basically a bunch of:

• with pytest.warns(..., match="...."): in tests,
• ignore:....:UserWarning in setup.cfg
• some reordering of warnings after errors so that they did not both get raised
• subtle issues like r""" instead of simple """ in docstrings (this gave a bunch of warnings about LaTeX commands interpreted as escapes that did not get caught)
• One eliminated Examples section from a docstring because it raised warnings that could not get caught
• A bunch of options (e.g. legacy=True) added to tests so that they did not trigger a warning.

All in all, it was a good exercise. The code did throw far too many warnings, and some of them were actually either relevant or safe to eliminate.

[codecov]

Codecov Report

Merging #738 (8383ad4) into main (23a692c) will decrease coverage by 0.04%.
The diff coverage is 93.54%.

@@            Coverage Diff             @@
##             main     #738      +/-   ##
==========================================
- Coverage   97.15%   97.12%   -0.04%     
==========================================
  Files          42       42              
  Lines        7872     7884      +12     
==========================================
+ Hits         7648     7657       +9     
- Misses        224      227       +3     

Impacted Files	Coverage Δ
stingray/fourier.py	99.74% <ø> (ø)
stingray/spectroscopy.py	82.22% <ø> (ø)
stingray/modeling/parameterestimation.py	86.03% <83.33%> (-0.01%)	⬇️
stingray/crossspectrum.py	98.21% <100.00%> (-0.28%)	⬇️
stingray/deadtime/fad.py	99.39% <100.00%> (ø)
stingray/io.py	98.50% <100.00%> (+<0.01%)	⬆️
stingray/modeling/posterior.py	93.51% <100.00%> (+0.10%)	⬆️
stingray/multitaper.py	99.15% <100.00%> (ø)
stingray/pulse/pulsar.py	98.67% <100.00%> (ø)

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[dhuppenkothen]

Lots of work in here! Thanks for doing this! Looks good to me.