From 17a8fd6742b1c612d44e600e19f721950613f8b0 Mon Sep 17 00:00:00 2001
From: mbesancon <mathieu.besancon@gmail.com>
Date: Mon, 9 Apr 2018 11:34:32 -0400
Subject: [PATCH] Docs (#8)

* added docs

* approx for float comparison

* readme

* skipped line ignore

* updated packages, no patch specification
---
 .gitignore        |  1 +
 README.md         | 44 ++++++++++++++++++++++++++++++++++++++++++++
 REQUIRE           |  6 +++---
 docs/make.jl      | 12 ++++++++++++
 docs/src/index.md | 14 ++++++++++++++
 test/runtests.jl  | 28 ++++++++++++++--------------
 6 files changed, 88 insertions(+), 17 deletions(-)
 create mode 100644 docs/make.jl
 create mode 100644 docs/src/index.md

diff --git a/.gitignore b/.gitignore
index 8c960ec..9e6791b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+docs/build
diff --git a/README.md b/README.md
index 4255de5..a45aed7 100644
--- a/README.md
+++ b/README.md
@@ -6,3 +6,47 @@
 
 [![codecov](https://codecov.io/gh/JuliaGraphs/LightGraphsMatching.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGraphs/LightGraphsMatching.jl)
 
+Matching algorithms on top of [LightGraphs](https://github.com/JuliaGraphs/LightGraphs).
+
+## Usage
+
+The results of any matching is returned as a `MatchingResult` struct
+containing the `mate` and `weight` fields.
+
+### Perfect matching
+
+```julia
+g =CompleteGraph(4)
+w =Dict{Edge,Float64}()
+w[Edge(1,3)] = 10
+w[Edge(1,4)] = 0.5
+w[Edge(2,3)] = 11
+w[Edge(2,4)] = 2
+w[Edge(1,2)] = 100
+
+# find the perfect matching of minimum weight
+match = minimum_weight_perfect_matching(g, w, 50)
+# match.mate[1] == 4
+# match.mate[4] == 1
+# match.mate[2] == 3
+# match.mate[3] == 2
+# match.weight ≈ 11.5
+```
+
+### Maximum weight matching
+
+A maximum weight matching is solved as a Linear Programming
+problem and requires a LP solver respecting the [MathProgBase](https://github.com/JuliaOpt/MathProgBase.jl) solver
+interface. See MathProgBase 
+[documentation](http://mathprogbasejl.readthedocs.io/en/latest/solvers.html) for more details.
+
+```julia
+using Cbc: CbcSolver #import a LP solver
+g = CompleteGraph(3)
+w = zeros(3,3)
+w[1,2] = 1
+w[3,2] = 1
+w[1,3] = 1
+match = maximum_weight_matching(g,CbcSolver(),w)
+# match.weight ≈ 1
+```
diff --git a/REQUIRE b/REQUIRE
index c76be4d..09c6d3f 100644
--- a/REQUIRE
+++ b/REQUIRE
@@ -1,5 +1,5 @@
 julia 0.6
-LightGraphs 0.9.0
-JuMP 0.13.2
+LightGraphs 0.12
+JuMP 0.13
 MatrixDepot
-BlossomV 0.1
+BlossomV 0.3
diff --git a/docs/make.jl b/docs/make.jl
new file mode 100644
index 0000000..02dec51
--- /dev/null
+++ b/docs/make.jl
@@ -0,0 +1,12 @@
+using Documenter
+using LightGraphsMatching
+import LightGraphs; const lg = LightGraphs
+
+makedocs(
+    modules = [LightGraphsMatching],
+    format = :html,
+    sitename = "LightGraphsMatching",
+	pages = Any[
+		"Getting started"         => "index.md",
+    ]
+)
diff --git a/docs/src/index.md b/docs/src/index.md
new file mode 100644
index 0000000..6886385
--- /dev/null
+++ b/docs/src/index.md
@@ -0,0 +1,14 @@
+```@meta
+CurrentModule = LightGraphsMatching
+DocTestSetup = quote
+    using LightGraphsMatching
+    import LightGraphs
+    const lg = LightGraphs
+end
+```
+
+```@autodocs
+Modules = [LightGraphsMatching]
+Pages = ["LightGraphsMatching.jl", "maximum_weight_matching.jl", "lp.jl", "blossomv.jl"]
+Order = [:function, :type]
+```
diff --git a/test/runtests.jl b/test/runtests.jl
index 135f5a1..38139d2 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -26,7 +26,7 @@ w = [
 ]
 match = maximum_weight_matching(g, CbcSolver(), w)
 @test match.mate[1] == 3
-@test match.weight == 3
+@test match.weight ≈ 3
 
 g = CompleteBipartiteGraph(2,2)
 w = zeros(4,4)
@@ -35,7 +35,7 @@ w[1,4] = 1.
 w[2,3] = 2.
 w[2,4] = 11.
 match = maximum_weight_maximal_matching(g, CbcSolver(), w)
-@test match.weight == 21
+@test match.weight ≈ 21
 @test match.mate[1] == 3
 @test match.mate[3] == 1
 @test match.mate[2] == 4
@@ -48,7 +48,7 @@ w[1,4] = 0.5
 w[2,3] = 11
 w[2,4] = 1
 match = maximum_weight_maximal_matching(g, CbcSolver(), w)
-@test match.weight == 11.5
+@test match.weight ≈ 11.5
 @test match.mate[1] == 4
 @test match.mate[4] == 1
 @test match.mate[2] == 3
@@ -63,7 +63,7 @@ w[2,4] = 1
 w[2,5] = -1
 w[2,6] = -1
 match = maximum_weight_maximal_matching(g,CbcSolver(),w,0)
-@test match.weight == 11.5
+@test match.weight ≈ 11.5
 @test match.mate[1] == 4
 @test match.mate[4] == 1
 @test match.mate[2] == 3
@@ -78,7 +78,7 @@ w[1,6] = 1
 w[1,5] = -1
 
 match = maximum_weight_maximal_matching(g,CbcSolver(),w,0)
-@test match.weight == 12
+@test match.weight ≈ 12
 @test match.mate[1] == 6
 @test match.mate[2] == 5
 @test match.mate[3] == -1
@@ -92,7 +92,7 @@ w[1,2] = 1
 w[3,2] = 1
 w[1,3] = 1
 match = maximum_weight_matching(g,CbcSolver(),w)
-@test match.weight == 1
+@test match.weight ≈ 1
 
 
 g = Graph(4)
@@ -106,7 +106,7 @@ w[1,4] = 3
 w[2,4] = 1
 
 match = maximum_weight_matching(g,CbcSolver(),w)
-@test match.weight == 3
+@test match.weight ≈ 3
 @test match.mate[1] == 4
 @test match.mate[2] == -1
 @test match.mate[3] == -1
@@ -118,7 +118,7 @@ add_edge!(g, 2,3)
 add_edge!(g, 3,1)
 add_edge!(g, 3,4)
 match = maximum_weight_matching(g,CbcSolver())
-@test match.weight == 2
+@test match.weight ≈ 2
 @test match.mate[1] == 2
 @test match.mate[2] == 1
 @test match.mate[3] == 4
@@ -131,7 +131,7 @@ w[1,3] = 1
 w[3,4] = 1
 
 match = maximum_weight_matching(g,CbcSolver(), w)
-@test match.weight == 2
+@test match.weight ≈ 2
 @test match.mate[1] == 2
 @test match.mate[2] == 1
 @test match.mate[3] == 4
@@ -144,7 +144,7 @@ w[1,3] = 5
 w[3,4] = 1
 
 match = maximum_weight_matching(g,CbcSolver(),w)
-@test match.weight == 5
+@test match.weight ≈ 5
 @test match.mate[1] == 3
 @test match.mate[2] == -1
 @test match.mate[3] == 1
@@ -169,7 +169,7 @@ match = minimum_weight_perfect_matching(g, w)
 @test match.mate[2] == 1
 @test match.mate[3] == 4
 @test match.mate[4] == 3
-@test match.weight == 600
+@test match.weight ≈ 600
 
 w = Dict(
         Edge(1, 2) => 500,
@@ -184,7 +184,7 @@ match = minimum_weight_perfect_matching(g, w)
 @test match.mate[2] == 4
 @test match.mate[3] == 1
 @test match.mate[4] == 2
-@test match.weight == 1400
+@test match.weight ≈ 1400
 
 g =CompleteBipartiteGraph(2,2)
 w =Dict{Edge,Float64}()
@@ -198,7 +198,7 @@ match = minimum_weight_perfect_matching(g, w)
 @test match.mate[4] == 1
 @test match.mate[2] == 3
 @test match.mate[3] == 2
-@test match.weight == -11.5
+@test match.weight ≈ -11.5
 
 
 g =CompleteGraph(4)
@@ -214,4 +214,4 @@ match = minimum_weight_perfect_matching(g, w, 50)
 @test match.mate[4] == 1
 @test match.mate[2] == 3
 @test match.mate[3] == 2
-@test match.weight == 11.5
+@test match.weight ≈ 11.5