[docs] refactor and re-organize the documentation

.vale.ini

@@ -9,5 +9,5 @@ BasedOnStyles = Vale, Google
 [*]
 TokenIgnores = (\$+.+?\$+)|(\]\(@(ref|id).+?\))
 
-[docs/src/faq.md]
+[docs/src/introduction/faq.md]
 Google.FirstPerson = OFF

docs/make.jl

@@ -203,25 +203,25 @@ Documenter.makedocs(
     pages = [
         "Introduction" => [
             "Home" => "index.md",
-            "Installation" => "installation.md",
-            "Quick Tutorial" => "quick_tutorial.md",
-            "FAQ" => "faq.md",
+            "introduction/installation.md",
+            "introduction/quick_tutorial.md",
+            "introduction/faq.md",
         ],
         "Examples" => examples_nav,
         "Manual" => [
-            "Basic Types" => "types.md",
-            "Supported Operations" => "operations.md",
-            "Complex-domain Optimization" => "complex-domain_optimization.md",
-            "Solvers" => "solvers.md",
-            "Advanced" => "advanced.md",
+            "manual/types.md",
+            "manual/operations.md",
+            "Complex-domain Optimization" => "manual/complex-domain_optimization.md",
+            "manual/solvers.md",
+            "manual/advanced.md",
         ],
         "Developer Docs" => [
-            "Problem Depot" => "problem_depot.md",
-            "Contributing" => "contributing.md",
-            "Credits" => "credits.md",
+            "developer/problem_depot.md",
+            "developer/contributing.md",
+            "developer/credits.md",
         ],
-        "Reference" => "reference.md",
-        "Release notes" => "release_notes.md",
+        "reference.md",
+        "release_notes.md",
     ],
 )
 

docs/src/contributing.md → docs/src/developer/contributing.md

@@ -1,5 +1,4 @@
-Contributing
-============
+# Contributing
 
 We'd welcome contributions to the Convex.jl package. Here are some
 short instructions on how to get started. If you don't know what you'd
@@ -14,8 +13,7 @@ like to contribute, you could
 Then submit a pull request (PR). (Let us know if it's a work in
 progress by putting \[WIP\] in the name of the PR.)
 
-Adding examples
----------------
+## Adding examples
 
  -   Take a look at our existing [usage
      examples](https://github.com/jump-dev/Convex.jl/tree/master/examples)
@@ -25,8 +23,7 @@ Adding examples
  -   We'll look it over, fix up anything that doesn't work, and merge
      it.
 
-Adding atoms
-------------
+## Adding atoms
 
 Here are the steps to add a new function or operation (atom) to
 Convex.jl. Let's say you're adding the new function $f$.
@@ -58,13 +55,7 @@ Convex.jl. Let's say you're adding the new function $f$.
  -   We'll look it over, fix up anything that doesn't work, and merge
      it.
 
-```@docs
-Convex.conic_form!
-Convex.new_conic_form!
-```
-
-Fixing the guts
----------------
+## Fixing the guts
 
 If you want to do a more major bug fix, you may need to understand how
 Convex.jl thinks about conic form. To do this, start by reading [the

docs/src/developer/credits.md

@@ -0,0 +1,29 @@
+# Credits
+
+Convex.jl was created, developed, and maintained by:
+
+ - [Jenny Hong](http://www.stanford.edu/~jyunhong/)
+ - [Karanveer Mohan](http://www.stanford.edu/~kvmohan/)
+ - [Madeleine Udell](http://www.stanford.edu/~udell/)
+ - [David Zeng](http://www.stanford.edu/~dzeng0/)
+
+Convex.jl is currently developed and maintained by the Julia community; see
+[Contributors](https://github.com/JuliaOpt/Convex.jl/graphs/contributors)
+for more.
+
+The Convex.jl developers also thank:
+
+ * the [JuliaOpt](http://www.juliaopt.org/) team:
+   [Iain Dunning](http://iaindunning.com/),
+   [Joey Huchette](http://www.mit.edu/~huchette/) and
+   [Miles Lubin](http://www.mit.edu/~mlubin/)
+ * [Stephen Boyd](http://www.stanford.edu/~boyd/), co-author of the book
+   [Convex Optimization](http://www.stanford.edu/~boyd/books.html)
+ * [Steven Diamond](http://www.stanford.edu/~stevend2/), developer of
+   [CVXPY](https://github.com/cvxgrp/cvxpy) and of a
+   [DCP tutorial website](http://dcp.stanford.edu/) to teach disciplined convex
+   programming.
+ * [Michael Grant](http://www.cvxr.com/bio), developer of [CVX](http://www.cvxr.com).
+ * [John Duchi](http://www.stanford.edu/~jduchi) and Hongseok Namkoong for
+    developing the [representation of power cones in terms of SOCP constraints](https://github.com/jump-dev/Convex.jl/raw/master/docs/supplementary/rational_to_socp.pdf)
+    used in this package.

docs/src/problem_depot.md → docs/src/developer/problem_depot.md

@@ -1,5 +1,4 @@
-Problem Depot
-=============
+# Problem Depot
 
 Convex.jl has a submodule, `ProblemDepot` which holds a collection of convex optimization problems. The problems are used by Convex itself to test and benchmark its code, but can also be used by solvers to test and benchmark their code. These tests have been used with many solvers at [ConvexTests.jl](https://github.com/ericphanson/ConvexTests.jl).
 
@@ -17,8 +16,7 @@ const MOI = Convex.MOI
 end
 ```
 
-How to write a ProblemDepot problem
------------------------------------
+## How to write a ProblemDepot problem
 
 The problems are organized into folders in `src/problem_depot/problems`. Each is written as a function, annotated by `@add_problem`, and a name, which is used to group the problems. For example, here is a simple problem:
 
@@ -65,8 +63,7 @@ if test
 end
 ```
 
-Benchmark-only problems
------------------------
+## Benchmark-only problems
 
 To add problems for benchmarking without tests, place problems in `src/problem_depot/problems/benchmark`, and include `benchmark` in the name. These problems will be automatically skipped during `run_tests` calls. For example, to benchmark the time it takes to add an SDP constraint, we have the problem
 
@@ -86,13 +83,3 @@ Note, we use `args...` in the function signature so that it may be called with t
 ```julia
 f(handle_problem!, ::Val{test}, atol, rtol, ::Type{T}) where {T, test}
 ```
-
-Reference
----------
-
-```@docs
-Convex.ProblemDepot.run_tests
-Convex.ProblemDepot.benchmark_suite
-Convex.ProblemDepot.foreach_problem
-Convex.ProblemDepot.PROBLEMS
-```