Suggestions for Documentation Improvements

[ccoffrin]

This is a list of points I ran into while developing the docstring-based documentation in #1058.

Structure

• Incorporating docstrings highlights the mix of manual and library docs, consider breaking these into two sections at the top level (like the Julia manual) (Refactor documentation into separate API reference #2380)
• Explore if there is a clean way to incorporate the epic notes in JuMP's code (For example, "Let S₊ be the cone of symmetric semidefinite matrices in" note in JuMP.jl) into docstrings that get into the developer docs.
• The current API docs bring in methods on a case-by-case basis. Consider using @autodocs to bringing in all methods ([docs] Add missing docstrings and fix doctests that arose as a result #2393)

Maintenance

• Go through all functions without doc strings and figure which are missing documentation (New issue: Exported functions with no doc #1825)
• Go through all functions with empty doc strings and add documentation (e.g. getvalue and getdual) (Part of Exported functions with no doc #1825)
• Do the type signatures in macros make sense? Is this the best way to document macro APIs?
• Status documentation should probably link and/or pull in MPB docs
• The list const var_cats should probably have documentation (No longer relevant)

[mlubin]

Is there anything actionable to do here for 0.19?

[mlubin]

Following the discussion in the gitter channel, we'll remove this from the 0.19 milestone. The main suggestion here that we should consider implementing is splitting docs into a manual and API reference like we do for MOI.

[odow]

Closing since these points are now largely achieved, and other issues track more specific suggestions, e.g., #1825, #2485