CLN/BUG: Allow assert_produces_warning to raise during an exception
Fixes this case that would not raise an `AssertionError` before

```
with pytest.raises(...):
    with tm.assert_produces_warning(UserWarning):
        raise ...
```
CI/CD notwithstanding, I'm having some trouble reviewing this PR.  It seems there are changes beyond the scope of the title?

IMO could benefit from breaking apart into smaller ones unless I'm missing something @mroeschke. There is an attribute cleanup and doc change in this PR, but otherwise the other changes correspond to `assert_produces_warning` now evaluating during exceptions. The changed tests have stale `assert_produces_warning`s that are testing that an exception is raised