Introduce deprecations page

[nicoddemus]

Got the page going, wanted to see what others think.

Documenting the deprecations in the CHANGELOG often is done too briefly, while I believe we should write down the rationale and provide examples on how to update the code. I think when users understand the reasoning behind deprecations they are much more understanding.

Also examples on how to update the code currently are often provided in the docstrings of the features we plan to remove, which will disappear when we effectively remove said feature.

The idea is to keep this page around "forever" as a reference for users which encounter ancient codebases and want to revive them.

fix #3996

[coveralls]

Coverage increased (+0.01%) to 93.825% when pulling c284154 on nicoddemus:deprecation-docs into 1f28096 on pytest-dev:master.

[codecov]

Codecov Report

Merging #3997 into master will decrease coverage by 0.24%.
The diff coverage is n/a.

@@            Coverage Diff            @@
##           master   #3997      +/-   ##
=========================================
- Coverage   94.34%   94.1%   -0.25%     
=========================================
  Files         108     108              
  Lines       23703   23698       -5     
  Branches     2353    2350       -3     
=========================================
- Hits        22363   22300      -63     
- Misses       1021    1075      +54     
- Partials      319     323       +4

Flag	Coverage Δ
#doctesting	?
#linux	94.1% <ø> (-0.25%)	⬇️
#nobyte	?
#numpy	28.16% <ø> (+0.06%)	⬆️
#pexpect	0% <ø> (ø)	⬆️
#py27	91.99% <ø> (-0.5%)	⬇️
#py34	92% <ø> (+0.03%)	⬆️
#py35	?
#py36	92.54% <ø> (+0.04%)	⬆️
#py37	?
#trial	31.04% <ø> (+0.06%)	⬆️
#xdist	18.44% <ø> (+0.02%)	⬆️

Impacted Files	Coverage Δ
src/_pytest/debugging.py	55.81% <0%> (-11.63%)	⬇️
testing/test_pdb.py	44.01% <0%> (-9.48%)	⬇️
src/_pytest/assertion/util.py	92.92% <0%> (-5.19%)	⬇️
src/_pytest/doctest.py	94.37% <0%> (-2.41%)	⬇️
testing/python/integration.py	89.36% <0%> (-2.13%)	⬇️
src/_pytest/assertion/rewrite.py	95.5% <0%> (-0.17%)	⬇️
testing/code/test_source.py	96.79% <0%> (-0.01%)	⬇️
testing/code/test_code.py	95.45% <0%> (+1.33%)	⬆️
src/_pytest/terminal.py	91.6% <0%> (+1.74%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1f28096...c284154. Read the comment docs.

[RonnyPfannschmidt]

i like what i see so far, having a detailed documentation is pretty helpfull

[nicoddemus]

Ready for review! 👍

[nicoddemus]

cc @okken

[okken]

Thanks Bruno. I think it’s a good idea.