jump-dev/Convex.jl

Suggestions for documentation improvements

Open

#344 opened on Nov 7, 2019

View on GitHub
 (4 comments) (0 reactions) (0 assignees)Julia (593 stars) (123 forks)batch import
documentationgood first issuehelp wanted

Description

The purpose of this issue is to collate suggestions for documentation improvements into a single issue. (We did thes quite successfully in JuMP https://github.com/jump-dev/JuMP.jl/issues/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

  • #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 https://github.com/jump-dev/Convex.jl/pull/574#discussion_r1458072804
  • Discuss numerical issues and limitations of SDP solvers https://github.com/jump-dev/Convex.jl/pull/574#discussion_r1458080972
  • 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 #653)

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
basic Julia knowledgefamiliarity with Convex.jldocumentation writing
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Pick an unchecked item from the checklist (e.g., 'Unify data formats' or 'Add more exposition to examples'). Review the linked PRs for context, especially #339 and #574. Look at existing documentation in the /docs/ directory and examples in the repository. Update the documentation with clearer explanations, add plots, or unify data formats. Reference the discussion in #574 for numerical issues and cvxpy differences.