DOC: optimize: remove inadvertent block quote indentation #13106

mdhaber · 2020-11-21T20:22:11Z

Many lists in optimize documentation are indented relative to the surrounding text. The indentation indicates to Sphinx that the
text is to be formatted as a block quote, and our theme represents that with a vertical bar. Much of this appears to be unintentional, and it's understandable since we're used to indenting all blocks in Python, but Sphinx has other ideas.

vs

This commit removes unnecessary indentation to eliminate these vertical bars.

I know we typically don't like these large cleanups, but I thought this might deserve an exception. Contributors (like me) will continue to copy the formatting they see in other documentation, assuming it is supposed to be that way, and rather than whittling down the bad formatting over time, it will continue to grow. So I thought maybe this deserves to be considered. Hopefully, it's pretty uncontroversial as it's almost all whitespace changes.

mdhaber · 2020-11-21T20:26:13Z

scipy/optimize/_linprog.py

@@ -142,13 +142,13 @@ def linprog_terse_callback(res):
            feasible solution is sought and the T has an additional row
            representing an alternate objective function.
        status : int
-            An integer representing the exit status of the optimization::
+            An integer representing the exit status of the optimization:


This is another thing that shows up occasionally - rendering return code lists as literal blocks. One could argue that it's supposed to be that way, but I think it's more important for it to be consistent.

This change isn't being displayed correctly. Comes out as a single sentence. https://22669-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.linprog_verbose_callback.html#scipy.optimize.linprog_verbose_callback

Literal blocks are easier to align on the screen, otherwise you get wonky lists which look quite ugly.

Literal blocks are easier to align on the screen, otherwise you get wonky lists which look quite ugly.

I agree that the bullets are too far to the left, but isn't that more of a problem with the Sphinx theme? I think that's something we can (and should) fix across the board with a change in the right place.

This change isn't being displayed correctly.

Thanks. It was supposed to be more like:

I'll fix.

Looks like I did fix this. Now it's:

https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.linprog_verbose_callback.html#scipy.optimize.linprog_verbose_callback

Many lists in the optimize documentation are indented relative to the surrounding text. The indentation indicates to Sphinx that the text is to be formatted as a block quote, and our theme represents that with a vertical bar. Much of this appears to be unintentional. This commit removes the extra indentation to eliminate these vertical bars.

andyfaff · 2020-11-22T03:56:02Z

This kind of change isn't going to result in a lot of PRs needing to be rebased to fix merge conflicts. I'll run through each of the doc pages once the build artefact has completed.

andyfaff · 2020-11-22T05:41:08Z

scipy/optimize/_dual_annealing.py

@@ -496,9 +496,9 @@ def dual_annealing(func, bounds, args=(), maxiter=1000,
        latest minimum found, and ``context`` has value in [0, 1, 2], with the
        following meaning:

-            - 0: minimum detected in the annealing process.


the documentation could do with a little polishing in this section, but that's out of scope of this PR.

andyfaff · 2020-11-22T05:45:05Z

scipy/optimize/_linprog.py

@@ -142,13 +142,13 @@ def linprog_terse_callback(res):
            feasible solution is sought and the T has an additional row
            representing an alternate objective function.
        status : int
-            An integer representing the exit status of the optimization::
+            An integer representing the exit status of the optimization:


This change isn't being displayed correctly. Comes out as a single sentence. https://22669-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.linprog_verbose_callback.html#scipy.optimize.linprog_verbose_callback

andyfaff · 2020-11-22T05:49:37Z

scipy/optimize/_minimize.py

@@ -121,8 +121,8 @@ def minimize(fun, x0, args=(), method=None, jac=None, hess=None,
        the Hessian. Available quasi-Newton methods implementing
        this interface are:

-            - `BFGS`;
-            - `SR1`.
+        - `BFGS` and


is 'and' required?

Sort of, because there was a period after SR1, suggesting some sort of attempt to make this a complete sentence. Maybe it's best to throw out the "and" and the period.

Now it is:

https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.minimize.html#scipy.optimize.minimize

andyfaff · 2020-11-22T05:50:10Z

scipy/optimize/_minimize.py


-            ``hessp(x, p, *args) ->  ndarray shape (n,)``
+            hessp(x, p, *args) ->  ndarray shape (n,)

        where x is a (n,) ndarray, p is an arbitrary vector with


surely some of these should be in backticks (out of scope for this PR)?

They render as code blocks because of the preceeding double-colon. Makes a lot of sense, right? : P

@mdhaber, @andyfaff might be referring to x, (n,), ndarray and p in line 142. But I think it is fine to consider such additional changes as out of scope for this PR.

Ah, of course. Yeah, there is a lot more to be fixed about the minimize docstring; let's aim this at the appearance of lists.

andyfaff · 2020-11-22T05:52:22Z

scipy/optimize/_minimize.py


        Constraints for COBYLA, SLSQP are defined as a list of dictionaries.
        Each dictionary with fields:

-            type : str


it'd be nice just to have new-style objects, and use new-style internally.

Hah reviewing the docs does stir those sorts of thoughts.

andyfaff · 2020-11-22T06:00:57Z

scipy/optimize/_shgo.py

-                The Jacobian of `fun` (only for SLSQP).
-            args : sequence, optional
-                Extra arguments to be passed to the function and Jacobian.
+        type : str


really wish we could use NonlinearConstraint as default and dump the dicts. Anyway, trust-constr accepts new-style constraints so is statement in the Note box correct? https://22669-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.shgo.html#scipy.optimize.shgo

It just wasn't updated when trust-constr was added. I snuck it in here.

Fixed note box:

https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.shgo.html#scipy.optimize.shgo

andyfaff · 2020-11-22T06:06:38Z

scipy/optimize/_shgo.py

+            its derivatives (Jacobian, Hessian).
+        options : dict, optional
+            Note that by default the tolerance is specified as
+            ``{ftol: 1e-12}``


Line 101 should have scipy.optimize.minimize in backticks

I will fix this one, but we could spend days fixing inconsistent use of backticks! We really need to decide what deserves double backticks and what should have just singles. NumPy guidelines say "Enclose variables in double backticks", but where do we draw the line between a "variable" and code? Why is it appropriate for the parameter names to be bold in the parameter list, italicized when we refer to them in the descriptions, and teletype when we actually type them in the IDE? If I had my way, all inline code would be teletype (bold/italicized as needed for emphasis) but without the gray box around, just as Matlab does it

But this is not the place : )

Fixed:

https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.shgo.html#scipy.optimize.shgo

andyfaff · 2020-11-22T06:07:01Z

scipy/optimize/_shgo.py

@@ -87,14 +87,14 @@ def shgo(func, bounds, args=(), constraints=None, n=100, iters=1, callback=None,
        Extra keyword arguments to be passed to the minimizer
        ``scipy.optimize.minimize`` Some important options could be:


full stop before 'some'

https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.shgo.html#scipy.optimize.shgo

andyfaff · 2020-11-22T06:08:00Z

scipy/optimize/_shgo.py

            Maximum number of function evaluations in the feasible domain.
            (Note only methods that support this option will terminate
            the routine at precisely exact specified value. Otherwise the
            criterion will only terminate during a global iteration)
-        * f_min
+        f_min


Added. Float, presumably.

https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.shgo.html#scipy.optimize.shgo

andyfaff · 2020-11-22T06:11:37Z

scipy/optimize/slsqp.py

-         9 : Iteration limit reached
+    Exit modes are defined as follows :
+
+    -1 : Gradient evaluation required (g & a)


these aren't being displayed correctly

https://22669-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.fmin_slsqp.html#scipy.optimize.fmin_slsqp

Thanks for catching that. I made them all on separate lines.

It would be nice if the blank lines added here weren't necessary, but it might be an acceptable compromise.

This is still not rendering properly: https://22691-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.fmin_slsqp.html#scipy.optimize.fmin_slsqp

I suspect you need an additional space before -1, to keep the left-most characters in each line aligned.

Fixed!
https://23582-1460385-gh.circle-artifacts.com/0/html-scipyorg/generated/scipy.optimize.fmin_slsqp.html#scipy.optimize.fmin_slsqp

scipy/optimize/_linprog.py

WarrenWeckesser · 2020-12-09T23:24:57Z

scipy/optimize/slsqp.py

-         7 : Rank-deficient equality constraint subproblem HFTI
-         8 : Positive directional derivative for linesearch
-         9 : Iteration limit reached
+    Exit modes are defined as follows :


Suggested change

Exit modes are defined as follows :

Exit modes are defined as follows:

…ption

WarrenWeckesser · 2020-12-10T12:27:53Z

scipy/optimize/slsqp.py

+    -1 : Gradient evaluation required (g & a)
+
+    0 : Optimization terminated successfully
+
+    1 : Function evaluation required (f & c)
+
+    2 : More equality constraints than independent variables
+
+    3 : More than 3*n iterations in LSQ subproblem
+
+    4 : Inequality constraints incompatible
+
+    5 : Singular matrix E in LSQ subproblem
+
+    6 : Singular matrix C in LSQ subproblem
+
+    7 : Rank-deficient equality constraint subproblem HFTI
+
+    8 : Positive directional derivative for linesearch
+
+    9 : Iteration limit reached


Elsewhere we use * in lists like this (e.g. see several cases being edited in this PR). That allows us to avoid the blank lines. Since we're already using that style in several places, we might as well use it here, too.

Suggested change

-1 : Gradient evaluation required (g & a)

0 : Optimization terminated successfully

1 : Function evaluation required (f & c)

2 : More equality constraints than independent variables

3 : More than 3*n iterations in LSQ subproblem

4 : Inequality constraints incompatible

5 : Singular matrix E in LSQ subproblem

6 : Singular matrix C in LSQ subproblem

7 : Rank-deficient equality constraint subproblem HFTI

8 : Positive directional derivative for linesearch

9 : Iteration limit reached

* -1 : Gradient evaluation required (g & a)

* 0 : Optimization terminated successfully

* 1 : Function evaluation required (f & c)

* 2 : More equality constraints than independent variables

* 3 : More than 3*n iterations in LSQ subproblem

* 4 : Inequality constraints incompatible

* 5 : Singular matrix E in LSQ subproblem

* 6 : Singular matrix C in LSQ subproblem

* 7 : Rank-deficient equality constraint subproblem HFTI

* 8 : Positive directional derivative for linesearch

* 9 : Iteration limit reached

(I think this change is in scope for this PR, because it is part of fixing the markup of lists.)

... but I'll let y'all decide if that is worthwhile--this is not a blocker for me. Even as it is now, this PR is a big improvement!

Elsewhere we use * in lists like this (e.g. see several cases being edited in this PR).

Yes, in some, but definitely not all. The only place where there is any consistency, as far as I've seen is within linprog, where bullets are not used.

Since there is not yet consensus about which style is best, I wrote above that I'd decided not to add or remove bullets elsewhere, so I'd like to leave this one alone.

mdhaber · 2021-05-12T21:37:41Z

@WarrenWeckesser do we still want this? With the current template, Sphinx does not render block quotes anymore, so this is less important.

mdhaber · 2021-12-06T19:36:29Z

There were some useful improvements to root finder documentation here (e.g. _root_broyden2_doc), but that was not really the point of this PR. Closing because there are bigger fish to fry.

mdhaber requested a review from andyfaff November 21, 2020 20:22

mdhaber commented Nov 21, 2020

View reviewed changes

mdhaber force-pushed the remove_unnecessary_indent branch from c38411e to cfff7a1 Compare November 22, 2020 03:40

andyfaff requested changes Nov 22, 2020

View reviewed changes

DOC: optimize: address @andyfaff comments in scipygh-13106

c57b2cf

mdhaber commented Nov 22, 2020

View reviewed changes

scipy/optimize/_linprog.py Show resolved Hide resolved

rgommers added Documentation Issues related to the SciPy documentation. Also check https://github.com/scipy/scipy.org maintenance Items related to regular maintenance tasks labels Nov 25, 2020

mdhaber mentioned this pull request Dec 9, 2020

ENH: stats: add Page's L test #12531

Merged

WarrenWeckesser reviewed Dec 9, 2020

View reviewed changes

DOC: optimize: fix indentation in slsqp docstring; fix broyden descri…

99cde83

…ption

WarrenWeckesser reviewed Dec 10, 2020

View reviewed changes

WarrenWeckesser approved these changes Dec 10, 2020

View reviewed changes

DOC: optimize: fix broyden documentation in its other location

89a1c37

mdhaber closed this Feb 1, 2021

mdhaber deleted the remove_unnecessary_indent branch February 1, 2021 07:50

mdhaber restored the remove_unnecessary_indent branch February 1, 2021 07:51

mdhaber reopened this Feb 1, 2021

tupui mentioned this pull request Mar 22, 2021

DOC: pydata sphinx theme #13724

Merged

mdhaber closed this Apr 9, 2021

mdhaber reopened this Apr 9, 2021

Merge branch 'master' into remove_unnecessary_indent

1550906

github-actions bot added scipy.optimize and removed Documentation Issues related to the SciPy documentation. Also check https://github.com/scipy/scipy.org labels Sep 3, 2021

mdhaber closed this Dec 6, 2021

mdhaber mentioned this pull request Jan 21, 2022

ENH: Make dual_annealing work with Bounds class #15453

Merged

mdhaber mentioned this pull request Jan 20, 2023

MAINT: remove divide by zero in differential_evolution #17793

Merged

		@@ -87,14 +87,14 @@ def shgo(func, bounds, args=(), constraints=None, n=100, iters=1, callback=None,
		Extra keyword arguments to be passed to the minimizer
		``scipy.optimize.minimize`` Some important options could be:

	Exit modes are defined as follows :
	Exit modes are defined as follows:

DOC: optimize: remove inadvertent block quote indentation #13106

DOC: optimize: remove inadvertent block quote indentation #13106

Conversation

mdhaber commented Nov 21, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Nov 22, 2020 • edited

Choose a reason for hiding this comment

mdhaber Dec 21, 2020 • edited

Choose a reason for hiding this comment

andyfaff commented Nov 22, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Nov 22, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Dec 10, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Nov 22, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Nov 22, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Nov 22, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber Dec 10, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

WarrenWeckesser Dec 10, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mdhaber commented May 12, 2021 • edited

mdhaber commented Dec 6, 2021

mdhaber commented Nov 21, 2020 •

edited

mdhaber Nov 22, 2020 •

edited

mdhaber Dec 21, 2020 •

edited

mdhaber Nov 22, 2020 •

edited

mdhaber Dec 10, 2020 •

edited

mdhaber Nov 22, 2020 •

edited

mdhaber Nov 22, 2020 •

edited

mdhaber Nov 22, 2020 •

edited

mdhaber Dec 10, 2020 •

edited

WarrenWeckesser Dec 10, 2020 •

edited

mdhaber commented May 12, 2021 •

edited