[docs] overhaul the docs (#194)

Author: odow

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Dualization = "191a621a-6537-11e9-281d-650236a99e60"
+ECOS = "e2685f51-7e38-5353-a97d-a921fd2c8199"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 
 [compat]
-Documenter = "0.24"
+Documenter = "1"

docs/make.jl

@@ -3,21 +3,27 @@
 # Use of this source code is governed by an MIT-style license that can be found
 # in the LICENSE.md file or at https://opensource.org/licenses/MIT.
 
-using Documenter, Dualization
+import Documenter
+import Dualization
 
-makedocs(
-    modules = [Dualization],
-    doctest = false,
-    clean = true,
-    # See https://github.com/JuliaDocs/Documenter.jl/issues/868
+Documenter.makedocs(
+    sitename = "Dualization.jl",
+    authors = "Guilherme Bodin, and contributors",
     format = Documenter.HTML(
         assets = ["assets/favicon.ico"],
         mathengine = Documenter.MathJax(),
         prettyurls = get(ENV, "CI", nothing) == "true",
     ),
-    sitename = "Dualization.jl",
-    authors = "Guilherme Bodin, and contributors",
-    pages = ["Home" => "index.md", "manual.md", "examples.md", "reference.md"],
+    pages = [
+        "Home" => "index.md",
+        "manual.md",
+        "mathematical_background.md",
+        "reference.md",
+    ],
+    modules = [Dualization],
+    checkdocs = :exports,
+    doctest = true,
+    clean = true,
 )
 
 Documenter.deploydocs(;

docs/src/examples.md

@@ -1,17 +1,35 @@
-# Dualization.jl Documentation
+# Dualization.jl
 
-Dualization.jl is a package written on top of MathOptInterface that allows users to write the dual of a JuMP model automatically.
-This package has two main features: the `dualize` function, which enables users to get a dualized JuMP model, and the `DualOptimizer`, which enables users to solve a problem by providing the solver the dual of the problem. 
+[Dualization.jl](https://github.com/jump-dev/Dualization.jl) is an extension
+package for [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl)
+that formulates the dual of conic optimization problems.
+
+Dualization.jl has two main features:
+
+ * The [`dualize`](@ref) function that computes the dual formulation of either
+   a [MathOptInterface.jl](https://github.com/jump-dev/MathOptInterface.jl) or a
+   [JuMP](https://github.com/jump-dev/JuMP.jl) model.
+ * The [`dual_optimizer`](@ref) function that creates a MathOptInterface-compatible
+   optimizer that solves the dual of the problem instead of the primal.
+
+## License
+
+[Dualization.jl](https://github.com/jump-dev/Dualization.jl) is licensed under
+the [MIT License](https://github.com/jump-dev/Dualization.jl/blob/master/LICENSE.md).
 
 ## Installation
 
-To install the package you can use `Pkg.add` as follows:
+Install Dualization using `Pkg.add`:
 ```julia
-pkg> add Dualization
+import Pkg
+Pkg.add("Dualization")
 ```
 
 ## Contributing
 
-Contributions to this package are more than welcome, if you find a bug or have any suggestions for the documentation please post it on the [github issue tracker](https://github.com/jump-dev/Dualization.jl/issues).
+Contributions to this package are more than welcome, if you find a bug or have
+any suggestions for the documentation please post it on the
+[GitHub issue tracker](https://github.com/jump-dev/Dualization.jl/issues).
 
-When contributing please note that the package follows the [JuMP style guide](https://jump.dev/JuMP.jl/stable/developers/style/).
+When contributing, please note that the package follows the
+[JuMP style guide](https://jump.dev/JuMP.jl/stable/developers/style/).