Merge branch 'master' into DominatingSet

.travis.yml

@@ -18,6 +18,6 @@ script:
 
 after_success:
     - julia -e 'using Pkg; cd(Pkg.dir("LightGraphs")); Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
-    - julia -e 'using Pkg; Pkg.add("Documenter")'
+    - julia -e 'using Pkg; ps=Pkg.PackageSpec(name="Documenter", version="0.19"); Pkg.add(ps); Pkg.pin(ps)'
     - julia -e 'using Pkg; cd(Pkg.dir("LightGraphs")); include(joinpath("docs", "make.jl"))'
 #    - export JULIA_NUM_THREADS=4; julia -e 'Pkg.add("PkgBenchmark"); using PkgBenchmark; benchmarkpkg("LightGraphs", promptoverwrite=false)'

docs/src/experimental.md

@@ -8,3 +8,11 @@ Code in this module is unstable and subject to change. Do not use any code in th
 ## Graph Isomorphism
 
 Here is the documentation for graph isomorphism functions.
+
+```@autodocs
+Modules = [LightGraphs]
+Pages   = [
+    "Experimental/isomorphism.jl",
+]
+Private = false
+```

docs/src/index.md

@@ -7,8 +7,7 @@ As such, *LightGraphs.jl* is the central package of the JuliaGraphs ecosystem. A
   * [MetaGraphs.jl](https://github.com/JuliaGraphs/MetaGraphs.jl): graphs with associated meta-data.
   * [SimpleWeightedGraphs.jl](https://github.com/JuliaGraphs/SimpleWeightedGraphs.jl): weighted graphs.
   * [GraphIO.jl](https://github.com/JuliaGraphs/GraphIO.jl): tools for importing and exporting graph objects using common file types like edgelists, GraphML, Pajek NET, and more.
-  * [GraphDataFrameBridge.jl](https://github.com/JuliaGraphs/GraphDataFrameBridge.jl): Tools for
-  converting edgelists stored in DataFrames into graphs (`MetaGraphs`, `MetaDiGraphs`).
+  * [GraphDataFrameBridge.jl](https://github.com/JuliaGraphs/GraphDataFrameBridge.jl): Tools for converting edgelists stored in DataFrames into graphs (`MetaGraphs`, `MetaDiGraphs`).
 
 
 ## Basic library examples

src/Experimental/isomorphism.jl

@@ -18,6 +18,17 @@ Run quick test to check if `g1 and `g2` could be isomorphic.
 
 If the result is `false`, then `g1` and `g2` are definitely not isomorphic,
 but if the result is `true` this is not guaranteed.
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> LightGraphs.Experimental.could_have_isomorph(PathGraph(3), StarGraph(4))
+false
+
+julia> LightGraphs.Experimental.could_have_isomorph(PathGraph(3), StarGraph(3))
+true
+```
 """
 function could_have_isomorph(g1::AbstractGraph, g2::AbstractGraph)
     nv(g1) == nv(g2) || return false

src/community/clique_percolation.jl

@@ -7,6 +7,23 @@ The parameter `k` defines the size of the clique to use in percolation.
  
 ### References
 - [Palla G, Derenyi I, Farkas I J, et al.] (https://www.nature.com/articles/nature03607)
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> clique_percolation(CliqueGraph(3, 2))
+2-element Array{BitSet,1}:
+ BitSet([4, 5, 6])
+ BitSet([1, 2, 3])
+
+julia> clique_percolation(CliqueGraph(3, 2), k=2)
+1-element Array{BitSet,1}:
+ BitSet([1, 2, 3, 4, 5, 6])
+
+julia> clique_percolation(CliqueGraph(3, 2), k=4)
+0-element Array{BitSet,1}
+```
 """
 function clique_percolation end
 

src/community/clustering.jl

@@ -5,6 +5,25 @@
 Return the [local clustering coefficient](https://en.wikipedia.org/wiki/Clustering_coefficient)
 for node `v` in graph `g`. If a list of vertices `vs` is specified, return a vector
 of coefficients for each node in the list.
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = SimpleGraph(4);
+
+julia> add_edge!(g, 1, 2);
+
+julia> add_edge!(g, 2, 4);
+
+julia> add_edge!(g, 4, 1);
+
+julia> local_clustering_coefficient(g, [1, 2, 3])
+3-element Array{Float64,1}:
+ 1.0
+ 1.0
+ 0.0
+```
 """
 function local_clustering_coefficient(g::AbstractGraph, v::Integer)
     ntriang, nalltriang = local_clustering(g, v)
@@ -78,6 +97,26 @@ Return the number of triangles in the neighborhood of node `v` in graph `g`.
 If a list of vertices `vs` is specified, return a vector of number of triangles
 for each node in the list. If no vertices are specified, return the number
 of triangles for each node in the graph.
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = SimpleGraph(4);
+
+julia> add_edge!(g, 1, 2);
+
+julia> add_edge!(g, 2, 4);
+
+julia> add_edge!(g, 4, 1);
+
+julia> triangles(g)
+4-element Array{Int64,1}:
+ 1
+ 1
+ 0
+ 1
+```
 """
 triangles(g::AbstractGraph, v::Integer) = local_clustering(g, v)[1]
 triangles(g::AbstractGraph, vs = vertices(g)) = local_clustering(g, vs)[1]
@@ -88,6 +127,17 @@ triangles(g::AbstractGraph, vs = vertices(g)) = local_clustering(g, vs)[1]
 
 Return the [global clustering coefficient](https://en.wikipedia.org/wiki/Clustering_coefficient)
 of graph `g`.
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> global_clustering_coefficient(StarGraph(4))
+0.0
+
+julia> global_clustering_coefficient(smallgraph(:housex))
+0.7894736842105263
+```
 """
 function global_clustering_coefficient(g::AbstractGraph)
     c = 0

src/community/core-periphery.jl

@@ -6,6 +6,25 @@ assignments (`1` for core and `2` for periphery) for each node in `g`.
 
 References:
     [Lip](http://arxiv.org/abs/1102.5511))
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> core_periphery_deg(StarGraph(5))
+5-element Array{Int64,1}:
+ 1
+ 2
+ 2
+ 2
+ 2
+
+julia> core_periphery_deg(PathGraph(3))
+3-element Array{Int64,1}:
+ 2
+ 1
+ 2
+```
 """
 function core_periphery_deg end
 @traitfn function core_periphery_deg(g::::(!IsDirected))

src/degeneracy.jl

@@ -16,6 +16,26 @@ Not implemented for graphs with self loops.
 * An O(m) Algorithm for Cores Decomposition of Networks,
     Vladimir Batagelj and Matjaz Zaversnik, 2003.
     http://arxiv.org/abs/cs.DS/0310049
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = PathGraph(5);
+
+julia> add_vertex!(g);
+
+julia> add_edge!(g, 5, 2);
+
+julia> core_number(g)
+6-element Array{Int64,1}:
+ 1
+ 2
+ 2
+ 2
+ 2
+ 0
+```
 """
 function core_number(g::AbstractGraph{T}) where T
     has_self_loops(g) && throw(ArgumentError("graph must not have self-loops"))
@@ -65,6 +85,32 @@ Not implemented for graphs with self loops.
 - An O(m) Algorithm for Cores Decomposition of Networks,
     Vladimir Batagelj and Matjaz Zaversnik, 2003.
     http://arxiv.org/abs/cs.DS/0310049
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = PathGraph(5);
+
+julia> add_vertex!(g);
+
+julia> add_edge!(g, 5, 2);
+
+julia> k_core(g, 1)
+5-element Array{Int64,1}:
+ 1
+ 2
+ 3
+ 4
+ 5
+
+julia> k_core(g, 2)
+4-element Array{Int64,1}:
+ 2
+ 3
+ 4
+ 5    
+```
 """
 function k_core(g::AbstractGraph, k=-1; corenum=core_number(g))
     if (k == -1)
@@ -94,6 +140,32 @@ Not implemented for graphs with parallel edges or self loops.
    Shai Carmi, Shlomo Havlin, Scott Kirkpatrick, Yuval Shavitt,
    and Eran Shir, PNAS  July 3, 2007   vol. 104  no. 27  11150-11154
    http://www.pnas.org/content/104/27/11150.full
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = PathGraph(5);
+
+julia> add_vertex!(g);
+
+julia> add_edge!(g, 5, 2);
+
+julia> k_shell(g, 0)
+1-element Array{Int64,1}:
+ 6
+
+julia> k_shell(g, 1)
+1-element Array{Int64,1}:
+ 1
+
+julia> k_shell(g, 2)
+4-element Array{Int64,1}:
+ 2
+ 3
+ 4
+ 5
+```
 """
 function k_shell(g::AbstractGraph, k=-1; corenum=core_number(g))
     if k == -1
@@ -109,7 +181,7 @@ Return a vector of vertices in the k-crust of `g`.
 If `k` is not specified, return the crust of the core with
 the largest degree.
 
-The k-crust is the graph `g` with the k-core removed.
+The k-crust is the graph `g` with the [`k-core`](@ref k_core) removed.
 
 ### Implementation Notes
 This definition of k-crust is different than the definition in References.
@@ -122,6 +194,35 @@ Not implemented for graphs with self loops.
    Shai Carmi, Shlomo Havlin, Scott Kirkpatrick, Yuval Shavitt,
    and Eran Shir, PNAS  July 3, 2007   vol. 104  no. 27  11150-11154
    http://www.pnas.org/content/104/27/11150.full
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = PathGraph(5);
+
+julia> add_vertex!(g);
+
+julia> add_edge!(g, 5, 2);
+
+julia> k_crust(g, 0)
+1-element Array{Int64,1}:
+ 6
+
+julia> k_crust(g, 1)
+2-element Array{Int64,1}:
+ 1
+ 6
+
+julia> k_crust(g, 2)
+6-element Array{Int64,1}:
+ 1
+ 2
+ 3
+ 4
+ 5
+ 6
+```
 """
 function k_crust(g, k=-1; corenum=core_number(g))
     if k == -1
@@ -135,7 +236,7 @@ end
 
 Return a vector of vertices in the k-corona of `g`. 
 
-The k-corona is the subgraph of vertices in the k-core which
+The k-corona is the subgraph of vertices in the [`k-core`](@ref k_core) which
 have exactly `k` neighbors in the k-core.
 
 ### Implementation Notes
@@ -148,6 +249,35 @@ Not implemented for graphs with parallel edges or self loops.
    A. V. Goltsev, S. N. Dorogovtsev, and J. F. F. Mendes,
    Phys. Rev. E 73, 056101 (2006)
    http://link.aps.org/doi/10.1103/PhysRevE.73.056101
+
+# Examples
+```jldoctest
+julia> using LightGraphs
+
+julia> g = PathGraph(5);
+
+julia> add_vertex!(g);
+
+julia> add_edge!(g, 5, 2);
+
+julia> k_corona(g, 0)
+1-element Array{Int64,1}:
+ 6
+
+julia> k_corona(g, 1)
+1-element Array{Int64,1}:
+ 1
+
+julia> k_corona(g, 2)
+4-element Array{Int64,1}:
+ 2
+ 3
+ 4
+ 5
+
+julia> k_corona(g, 3)
+0-element Array{Int64,1}
+```
 """
 function k_corona(g::AbstractGraph, k; corenum=core_number(g))
     kcore = k_core(g, k)