Repository: scipy/scipy

Issue:
Docstring improvements for optimize.minimize_scalar
The "(see here)" links for the various methods (brent, bounded, golden) of optimize.minimize_scalar should point to the notes below, rather than to the specialized pages
http://docs.scipy.org/doc/scipy/reference/optimize.minimize_scalar-bounded.html#optimize-minimize-scalar-bounded
http://docs.scipy.org/doc/scipy/reference/optimize.minimize_scalar-golden.html#optimize-minimize-scalar-golden
http://docs.scipy.org/doc/scipy/reference/optimize.minimize_scalar-brent.html#optimize-minimize-scalar-brent
which aren't very useful.

Also, the specialized pages for "golden" and "brent" display a different function signature that the page for minimize_scalar, i.e. they pass "brack" as a key to the "options" dictionary rather than using a keyword argument "bracket".



Discussion:
@rgommers  @anntzer is this ff142f8e9b3491567aed91f6353881a38bcc3546 what was supposed to be done?

@manipalsingh013 I commented on your PR. 

Hi, 
Is there still some work to be done on this issue?
If yes, I can take it.
Looks like #5771 was the PR in question (just to x-ref them)
and as far as I can tell it is still open since the keyword name still reads as `brack` (assuming this is the actual problem)
OK, I see. This change could be confusing, because in optimize/optimize.py there is actually a function called 'bracket' which is used in get_bracket_info method of class Brent. In that case we would change brack->bracket in public functions, but not in the class.
What is the problem?
---------------------------
Confusing "options" in desctiption of minimizing functions (brent, bounded, golden).

> scipy.optimize.minimize_scalar(fun, args=(), method='golden', tol=None, options={'xtol': 1.4901161193847656e-08, 'brack': None, 'func': None, 'maxiter': 5000})


Where is the problem?
-------------------------------
I investigated this matter a bit and the documentation is created with use of 
`doc/source/scipyoptdoc.py`.

The minimizing functions  are using helper functions, like
`    def _minimize_scalar_brent(func, brack=None, args=(),
         xtol=1.48e-8, maxiter=500,
         **unknown_options):
`
from where the **dosctring** is taken and also **"options"** dictionary in `minimize_scalar` arguments is generated based on this function's arguments. That is where the confusion is born.

Possible solution
---------------------
- disable "options" dictionary display for the minimizing functions
- allow in "options" only ones not mentioned before (more tricky, as the names are not unified brack-> bracket, xto->tol,...)
Why are they confusing?

There is a risk of double define function parameters in one call.

In the call of minimize scalar for brent method we use following parameters:
```
 minimize_scalar(fun, bracket=None, bounds=None, args=(),
                    method='brent', tol=None, options=None)

```
Parameters **fun, bracket, args** and **options** are used for function `_minimize_scalar_brent` called as a result:
```
 return _minimize_scalar_brent(fun, bracket, args, **options)
```
In documentation we have:

> scipy.optimize.minimize_scalar(fun, args=(), method='brent', tol=None, options={'xtol': 1.48e-08, 'brack': None, 'func': None, 'maxiter': 500})

which has few pairs of arguments which in fact are the same:
- `fun` - `func`
- `tol` - `xtol`
- `bracket` is already in the call of `_minimize_scalar_brent` as a positional argument and if you provide `brent` in `options` it will be provided twice - once as None (because in the documentation there is no `bracket` keywors) and once by user with `brack` keyword.

@rgommers , I would like to work on the issue :)
(If not done). May I work on it?
@urstrulykkr please go for it, no need to ask for permission:)
surething :)

Resolving patch:
diff --git a/scipy/optimize/_minimize.py b/scipy/optimize/_minimize.py
--- a/scipy/optimize/_minimize.py
+++ b/scipy/optimize/_minimize.py
@@ -723,11 +723,13 @@ def minimize_scalar(fun, bracket=None, bounds=None, args=(),
     method : str or callable, optional
         Type of solver.  Should be one of:
 
-            - 'Brent'     :ref:`(see here) <optimize.minimize_scalar-brent>`
-            - 'Bounded'   :ref:`(see here) <optimize.minimize_scalar-bounded>`
-            - 'Golden'    :ref:`(see here) <optimize.minimize_scalar-golden>`
+            - :ref:`Brent <optimize.minimize_scalar-brent>`
+            - :ref:`Bounded <optimize.minimize_scalar-bounded>`
+            - :ref:`Golden <optimize.minimize_scalar-golden>`
             - custom - a callable object (added in version 0.14.0), see below
 
+        See the 'Notes' section for details of each solver.
+
     tol : float, optional
         Tolerance for termination. For detailed control, use solver-specific
         options.


Test patch: