sagemathgh-39043: Some documentation clean-up

    
Consolidate the description. Previously it was scattered into 3
different places.

also some minor changes (now `mwrank_lib` is the default as I read from
the code)

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion. (not aware of one)
- [x] I have created tests covering the changes. (no functional change)
- [x] I have updated the documentation and checked the documentation
preview.
    
URL: sagemath#39043
Reported by: user202729
Reviewer(s): Travis Scrimshaw, user202729

src/sage/libs/eclib/interface.py

@@ -268,21 +268,28 @@ def two_descent(self, verbose=True, selmer_only=False, first_limit=20,
 
         - ``selmer_only`` -- boolean (default: ``False``); ``selmer_only`` switch
 
-        - ``first_limit`` -- integer (default: 20); bound on `|x|+|z|` in
-          quartic point search
-
-        - ``second_limit`` -- integer (default: 8); bound on
-          `\log \max(|x|,|z|)`, i.e. logarithmic
-
-        - ``n_aux`` -- integer (default: -1); (only relevant for general
-          2-descent when 2-torsion trivial) number of primes used for
-          quartic search.  ``n_aux=-1`` causes default (8) to be used.
-          Increase for curves of higher rank.
-
-        - ``second_descent`` -- boolean (default: ``True``); (only relevant
-          for curves with 2-torsion, where mwrank uses descent via
-          2-isogeny) flag determining whether or not to do second
-          descent.  *Default strongly recommended.*
+        - ``first_limit`` -- integer (default: 20); naive height bound on
+          first point search on quartic homogeneous spaces (before
+          testing local solubility; very simple search with no
+          overheads).
+
+        - ``second_limit`` -- integer (default: 8); logarithmic height bound on
+          second point search on quartic homogeneous spaces (after
+          testing local solubility; sieve-assisted search)
+
+        - ``n_aux`` -- integer (default: -1); if positive, the number of
+          auxiliary primes used in sieve-assisted search for quartics.
+          If -1 (the default) use a default value (set in the eclib
+          code in ``src/qrank/mrank1.cc`` in DEFAULT_NAUX: currently 8).
+          Only relevant for curves with no 2-torsion, where full
+          2-descent is carried out.  Worth increasing for curves
+          expected to be of rank > 6 to one or two more than the
+          expected rank.
+
+        - ``second_descent`` -- boolean (default: ``True``); flag specifying
+          whether or not a second descent will be carried out.  Only relevant
+          for curves with 2-torsion.  Recommended left as the default except for
+          experts interested in details of Selmer groups.
 
         OUTPUT: nothing
 

src/sage/libs/eclib/mwrank.pyx

@@ -992,29 +992,11 @@ cdef class _two_descent:
           points.  Useful as a faster way of getting an upper bound on
           the rank.
 
-        - ``firstlim`` -- integer (default: 20); naive height bound on
-          first point search on quartic homogeneous spaces (before
-          testing local solubility; very simple search with no
-          overheads).
-
-        - ``secondlim`` -- integer (default: 8); naive height bound on
-          second point search on quartic homogeneous spaces (after
-          testing local solubility; sieve-assisted search)
-
-        - ``n_aux`` -- integer (default: -1); if positive, the number of
-          auxiliary primes used in sieve-assisted search for quartics.
-          If -1 (the default) use a default value (set in the eclib
-          code in ``src/qrank/mrank1.cc`` in DEFAULT_NAUX: currently 8).
-          Only relevant for curves with no 2-torsion, where full
-          2-descent is carried out.  Worth increasing for curves
-          expected to be of rank > 6 to one or two more than the
-          expected rank.
-
-        - ``second_descent`` -- integer (default: 1); flag specifying
-          whether or not a second descent will be carried out (yes if
-          1, the default; no if 0).  Only relevant for curves with
-          2-torsion.  Recommended left as the default except for
-          experts interested in details of Selmer groups.
+        - ``firstlim``, ``secondlim``, ``n_aux``, ``second_descent`` --
+          see ``first_limit``, ``second_limit``, ``n_aux``, ``second_descent``
+          respectively in :meth:`~sage.libs.eclib.interface.mwrank_EllipticCurve.two_descent`
+          (although ``second_descent`` here is ``1`` or ``0`` instead of ``True`` or ``False``
+          respectively)
 
         OUTPUT: none
 

src/sage/modules/free_module_element.pyx

@@ -4047,7 +4047,7 @@ cdef class FreeModuleElement(Vector):   # abstract base class
         Differentiate with respect to var by differentiating each element
         with respect to var.
 
-        .. seealso:
+        .. SEEALSO::
 
            :meth:`derivative`
 

src/sage/schemes/elliptic_curves/ell_rational_field.py

@@ -808,16 +808,28 @@ def two_descent(self, verbose=True,
 
         - ``selmer_only`` -- boolean (default: ``False``); selmer_only switch
 
-        - ``first_limit`` -- (default: 20) firstlim is bound
-          on x+z second_limit- (default: 8) secondlim is bound on log max
-          x,z , i.e. logarithmic
-
-        - ``n_aux`` -- (default: -1) n_aux only relevant for
-          general 2-descent when 2-torsion trivial; n_aux=-1 causes default
-          to be used (depends on method)
-
-        - ``second_descent`` -- (default: ``True``)
-          second_descent only relevant for descent via 2-isogeny
+        - ``first_limit`` -- integer (default: 20); naive height bound on
+          first point search on quartic homogeneous spaces (before
+          testing local solubility; very simple search with no
+          overheads).
+
+        - ``second_limit`` -- integer (default: 8); logarithmic height bound on
+          second point search on quartic homogeneous spaces (after
+          testing local solubility; sieve-assisted search)
+
+        - ``n_aux`` -- integer (default: -1); if positive, the number of
+          auxiliary primes used in sieve-assisted search for quartics.
+          If -1 (the default) use a default value (set in the eclib
+          code in ``src/qrank/mrank1.cc`` in DEFAULT_NAUX: currently 8).
+          Only relevant for curves with no 2-torsion, where full
+          2-descent is carried out.  Worth increasing for curves
+          expected to be of rank > 6 to one or two more than the
+          expected rank.
+
+        - ``second_descent`` -- boolean (default: ``True``); flag specifying
+          whether or not a second descent will be carried out.  Only relevant
+          for curves with 2-torsion.  Recommended left as the default except for
+          experts interested in details of Selmer groups.
 
         OUTPUT:
 
@@ -2256,9 +2268,9 @@ def gens(self, proof=None, **kwds):
 
         - ``algorithm`` -- one of the following:
 
-          - ``'mwrank_shell'`` -- default; call mwrank shell command
+          - ``'mwrank_lib'`` -- default; call mwrank C library
 
-          - ``'mwrank_lib'`` -- call mwrank C library
+          - ``'mwrank_shell'`` -- call mwrank shell command
 
           - ``'pari'`` -- use ellrank in pari
 
@@ -2268,7 +2280,11 @@ def gens(self, proof=None, **kwds):
         - ``use_database`` -- boolean (default: ``True``); if ``True``, attempts to
           find curve and gens in the (optional) database
 
-        - ``descent_second_limit`` -- (default: 12) used in 2-descent
+        - ``descent_second_limit`` -- (default: 12); logarithmic height bound on
+          second point search on quartic homogeneous spaces (after
+          testing local solubility; sieve-assisted search). Used in 2-descent.
+          See also ``second_limit``
+          in :meth:`~sage.libs.eclib.interface.mwrank_EllipticCurve.two_descent`
 
         - ``sat_bound`` -- (default: 1000) bound on primes used in
           saturation.  If the computed bound on the index of the