DOC: Improve replace docstring
xref #17673
closes #13852
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

I have tried to separate the docstrings for series and dataframe as suggested in the original issue but can try to combine them if that works better.

As noted in the original issue, ``replace`` can do a lot things and I've tried to cover most of them with the examples but would welcome other suggestions.