Suggestions for documentation improvements

[ericphanson]

The purpose of this issue is to collate suggestions for documentation improvements into a single issue. (We did thes quite successfully in JuMP jump-dev/JuMP.jl#2348).

If you are looking to contribute to Convex.jl, pick a topic off the list below. If you have an idea for an improvement, please leave comment. Any other fixes or improvements (such as was done with #340) would be very welcome as well, as well as new examples.

Items

• Switch examples to use Literate.jl and update to 1.0 #339 revamped the examples so they run on Julia 1.0 and so that they show up as part of the docs (see on the sidebar of https://www.juliaopt.org/Convex.jl/dev/ once that is merged), and standardized all the plotting to use Plots.jl.
• Have CI fail if examples don't run
• Unify data formats
• speed up the examples; currently huber_regression, logistic_regression and tomography are somewhat slow (see https://travis-ci.org/JuliaOpt/Convex.jl/jobs/608984432, but note that the earlier examples are penalized more since they have to compile Convex and Plots etc. I think chebyshev_center is only slow there since it's the first example to use Plots).
• Add more exposition to some of the examples. Some of them are just code without any description. It would great to have more explanations along with the code. More plots and visualizations are also always nice :)
• Note differences to cvxpy. See [docs] refactor and re-organize the documentation #574 (comment)
• Discuss numerical issues and limitations of SDP solvers [docs] refactor and re-organize the documentation #574 (comment)
• discuss partially specified problems
• discuss the differences between reformulations and atoms (atoms can customize sign/vexity/monotonicity, can use MOI-level stuff in conic_form!, and can delay things to conic_form time to support fix!/free!, xref _dot_multiply uses evaluate, therefore breaks fix!/free! #653)

[odow]

• see [docs] refactor and re-organize the documentation #574 (comment)

[ericphanson]

Have CI fail if examples don't run

I believe that works correctly now

[odow]

I'd like to have a CVXPY type list of all atoms supported by Convex.jl:
https://www.cvxpy.org/api_reference/cvxpy.atoms.other_atoms.html

I think we could have a standard docstring template, and then a single page of docstrings in the docs.

[ericphanson]

I think we can probably check off "speed up examples"; the current docs build is 9 mins total (from here), and locally running all the examples takes 2.5 mins first run, 1.5 mins second run, which seems fine. I think these used to be slower (maybe had perf issues that have been since fixed).