Added some documentation in the developer's guide regarding deprecation

[SandwichGouda]

In PR #37721, I attempted to deprecate the ring keyword argument in the matrix constructor
using @rename_keyword documented here.
It did not work. The code compiled exactly as if the decorator wasn't there.
I asked @mkoeppe why, he answered it "would be worth investigating and documenting".
After some investigation, I came to the conclusion that developers cannot use @rename_keyword and
other such decorators in Cython files.
My solution was to use deprecation_cython (this was accepted and merged).
Since many other developers might end up having the exact same problem, I simply suggest redirecting them
to deprecation_cython, by adding what's necessary in the docs.
In this regard, I added a paragraph mentioning this in the Developer's guide, as all of this was totally absent from documentation.

This way other developers won't need to investigate and spend time debugging non-working code. :)

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

⌛ Dependencies

[mkoeppe]

Thanks for preparing this.
Would you have a chance to check whether the use of the decorator in src/sage/modular/arithgroup/farey_symbol.pyx works?

[SandwichGouda]

Yep, I did that : it's the only @rename_keyword that appears in a .pyx file when using git grep @rename_keyword.
Actually, the old keyword still works, but the decorator does not return any deprecation.
Obviously, it should : this is the whole point of @rename_keyword. Otherwise, we would just rename keywords without deprecating them. That's why I suggested these changes in the docs.

[mkoeppe]

Could you prepare a fix for this one use?

[SandwichGouda]

You mean, changing the code of src/sage/modular/arithgroup/farey_symbol.pyx (only) ?
If that's what you mean, I suggest we basically remove the decorator to keep only the new keyword. The git blame shows that this was added 11 years ago...
It is high time we update the code remove this utterly old thing. Eleven years has been more than enough for people to get used to the new keyword :)

[github-actions]

Documentation preview for this PR (built with commit 4122508; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[mkoeppe]

OK, updating all of these color/rgbcolor renames is of course a better solution. That would belong on a separate PR

[mkoeppe]

Suggested change

	just use ``deprecation_cython()`` instead. The usage of ``deprecation_cython()``
	is exactly the same as ``deprecation()``.
	just use :func:`~sage.misc.superseded.deprecation_cython` instead. The usage of :func:`~sage.misc.superseded.deprecation_cython`
	is exactly the same as :func:`~sage.misc.superseded.deprecation`.

[mkoeppe]

Suggested change

	Deprecation
	===========
	Deprecation
	===========

[SandwichGouda]

I just made the suggested changes by @mkoeppe, but there's a doctest that fails :

sage -t --long --random-seed=286735480429121101562228604801325644303 src/sage/libs/gap/element.pyx  # 69 doctests failed
----------------------------------------------------------------------
Total time for all tests: 6583.0 seconds
    cpu time: 8850.3 seconds
    cumulative wall time: 9215.3 seconds
Features detected for doctesting: conway_polynomials,cvxopt,database_ellcurves,database_graphs,fpylll,gap_package_polycyclic,gfan,jmol,lrcalc_python,mpmath,nauty,networkx,numpy,palp,pexpect,pillow,polytopes_db,pplpy,primecountpy,ptyprocess,pyparsing,sage.combinat,sage.geometry.polyhedron,sage.graphs,sage.groups,sage.libs.braiding,sage.libs.ecl,sage.libs.flint,sage.libs.gap,sage.libs.linbox,sage.libs.m4ri,sage.libs.ntl,sage.libs.pari,sage.libs.singular,sage.misc.cython,sage.modular,sage.modules,sage.numerical.mip,sage.plot,sage.rings.complex_double,sage.rings.finite_rings,sage.rings.function_field,sage.rings.number_field,sage.rings.padics,sage.rings.polynomial.pbori,sage.rings.real_double,sage.rings.real_mpfr,sage.schemes,sage.symbolic,sagemath_doc_html,scipy,singular,sphinx,sympy,threejs
Running pytest on ['/sage/src/sage', '/sage/src/sage_setup', '/sage/src/sage_docbuild', '/sage/src/doc'] with options []
============================= test session starts ==============================
platform linux -- Python 3.10.12, pytest-8.1.1, pluggy-1.4.0
rootdir: /sage/src
configfile: tox.ini
plugins: xdist-3.5.0, mock-3.14.0, anyio-4.0.0, hypothesis-6.100.1
collected 61 items / 2 skipped

src/sage/doctest/parsing_test.py ...........                             [ 18%]
src/sage/manifolds/differentiable/examples/symplectic_space_test.py .... [ 24%]
                                                                         [ 24%]
src/sage/manifolds/differentiable/symplectic_form_test.py .............. [ 47%]
.....................                                                    [ 81%]
src/sage/manifolds/differentiable/tensorfield_paral_test.py .            [ 83%]
src/sage/numerical/backends/cvxopt_backend_test.py ..                    [ 86%]
src/sage/numerical/backends/glpk_backend_test.py ..                      [ 90%]
src/sage/numerical/backends/glpk_exact_backend_test.py ..                [ 93%]
src/sage/numerical/backends/interactivelp_backend_test.py ..             [ 96%]
src/sage/numerical/backends/ppl_backend_test.py ..                       [100%]

================== 61 passed, 2 skipped in 101.78s (0:01:41) ===================
Error: Process completed with exit code 1.

Any idea why ?
(Note : the tests ran automatically 7 hours ago and were successful, with the original code (the same code as when I opened the PR, i.e. the code @mkoeppe made suggestions onto))

[mkoeppe]

These sporadic failures in pytest are unrelated; that's tracked in #37536

Actually, now I saw the first line; that's probably either #37289 or #37026

[mkoeppe]

LGTM,. thanks.