Documentation page for packages that extend Graphs.jl

[mxhbl]

It was suggested by @Krastanov to include a documentation page mentioning external packages that extend the functionality of Graphs.jl. While this already exists for packages that implement custom graph types, this PR adds a documentation page for packages that implement additional algorithms (GraphsColoring, GraphsMatching, ...), or wrap external graph libraries in a compatible way (Igraphs, NautyGraphs, ...).

I am not sure how to best add these packages to the documentation, but I hope that my initial attempt here can serve as a starting point for discussion. The text describing the various packages in particular should be seen as placeholder text -- ideally, the package descriptions would be rewritten/improved by the respective package authors.

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	master	945cb23...	master / 945cb23...
centrality/digraphs/betweenness_centrality	16.3 ± 0.59 ms	16 ± 0.37 ms	1.02 ± 0.044
centrality/digraphs/closeness_centrality	11.5 ± 0.44 ms	11.1 ± 0.41 ms	1.03 ± 0.055
centrality/digraphs/degree_centrality	2.08 ± 1.8 μs	1.97 ± 0.19 μs	1.06 ± 0.93
centrality/digraphs/katz_centrality	0.876 ± 0.077 ms	0.875 ± 0.055 ms	1 ± 0.11
centrality/digraphs/pagerank	0.0366 ± 0.0054 ms	0.0364 ± 0.00055 ms	1 ± 0.15
centrality/graphs/betweenness_centrality	28.9 ± 1.4 ms	29.1 ± 1.3 ms	0.995 ± 0.066
centrality/graphs/closeness_centrality	21 ± 0.26 ms	21.3 ± 0.39 ms	0.986 ± 0.022
centrality/graphs/degree_centrality	1.49 ± 0.16 μs	1.5 ± 0.18 μs	0.993 ± 0.16
centrality/graphs/katz_centrality	1.03 ± 0.065 ms	1.03 ± 0.064 ms	1.01 ± 0.089
connectivity/digraphs/strongly_connected_components	0.0431 ± 0.0022 ms	0.043 ± 0.0013 ms	1 ± 0.059
connectivity/graphs/connected_components	24.6 ± 1.2 μs	24.3 ± 0.74 μs	1.01 ± 0.057
core/edges/digraphs	7.79 ± 0.021 μs	7.74 ± 0.071 μs	1.01 ± 0.0096
core/edges/graphs	17.4 ± 0.071 μs	15.8 ± 0.15 μs	1.1 ± 0.011
core/has_edge/digraphs	5.28 ± 0.49 μs	5.2 ± 0.37 μs	1.02 ± 0.12
core/has_edge/graphs	5.7 ± 0.94 μs	5.58 ± 0.41 μs	1.02 ± 0.18
core/nv/digraphs	0.361 ± 0.019 μs	0.361 ± 0.01 μs	1 ± 0.059
core/nv/graphs	0.38 ± 0.01 μs	0.371 ± 0.01 μs	1.02 ± 0.039
edges/fille	8.35 ± 0.99 μs	8.63 ± 0.97 μs	0.967 ± 0.16
edges/fillp	5.61 ± 4.6 μs	5.3 ± 4.3 μs	1.06 ± 1.2
edges/tsume	2.56 ± 0.06 μs	2.6 ± 0.15 μs	0.988 ± 0.062
edges/tsump	2.52 ± 0.099 μs	2.48 ± 0.031 μs	1.02 ± 0.042
insertions/SG(n,e) Generation	25 ± 4 ms	24.8 ± 4 ms	1.01 ± 0.23
parallel/egonet/twohop	0.298 ± 0.011 s	0.298 ± 0.0081 s	1 ± 0.047
parallel/egonet/vertexfunction	2.3 ± 0.17 ms	2.29 ± 0.16 ms	1 ± 0.1
serial/egonet/twohop	0.294 ± 0.01 s	0.31 ± 0.018 s	0.948 ± 0.065
serial/egonet/vertexfunction	2.21 ± 0.13 ms	2.28 ± 0.15 ms	0.971 ± 0.087
traversals/digraphs/bfs_tree	0.0498 ± 0.01 ms	0.0496 ± 0.0053 ms	1 ± 0.23
traversals/digraphs/dfs_tree	0.0639 ± 0.0097 ms	0.0636 ± 0.0087 ms	1 ± 0.21
traversals/graphs/bfs_tree	0.0538 ± 0.003 ms	0.0532 ± 0.0021 ms	1.01 ± 0.068
traversals/graphs/dfs_tree	0.0659 ± 0.0051 ms	0.066 ± 0.0032 ms	0.998 ± 0.091
time_to_load	0.545 ± 0.0063 s	0.553 ± 0.0059 s	0.986 ± 0.016

Memory benchmarks

	master	945cb23...	master / 945cb23...
centrality/digraphs/betweenness_centrality	0.29 M allocs: 24 MB	0.29 M allocs: 24 MB	1
centrality/digraphs/closeness_centrality	18.6 k allocs: 14.5 MB	18.6 k allocs: 14.5 MB	1
centrality/digraphs/degree_centrality	8 allocs: 5.01 kB	8 allocs: 5.01 kB	1
centrality/digraphs/katz_centrality	2.63 k allocs: 2.83 MB	2.63 k allocs: 2.83 MB	1
centrality/digraphs/pagerank	21 allocs: 14.9 kB	21 allocs: 14.9 kB	1
centrality/graphs/betweenness_centrality	0.545 M allocs: 0.0313 GB	0.545 M allocs: 0.0313 GB	1
centrality/graphs/closeness_centrality	19.3 k allocs: 14 MB	19.3 k allocs: 14 MB	1
centrality/graphs/degree_centrality	10 allocs: 5.43 kB	10 allocs: 5.43 kB	1
centrality/graphs/katz_centrality	2.96 k allocs: 3.1 MB	2.96 k allocs: 3.1 MB	1
connectivity/digraphs/strongly_connected_components	1.05 k allocs: 0.075 MB	1.05 k allocs: 0.075 MB	1
connectivity/graphs/connected_components	0.061 k allocs: 22.5 kB	0.061 k allocs: 22.5 kB	1
core/edges/digraphs	3 allocs: 0.0938 kB	3 allocs: 0.0938 kB	1
core/edges/graphs	3 allocs: 0.0938 kB	3 allocs: 0.0938 kB	1
core/has_edge/digraphs	20 allocs: 12.6 kB	20 allocs: 12.6 kB	1
core/has_edge/graphs	28 allocs: 13.8 kB	28 allocs: 13.8 kB	1
core/nv/digraphs	3 allocs: 0.0938 kB	3 allocs: 0.0938 kB	1
core/nv/graphs	3 allocs: 0.0938 kB	3 allocs: 0.0938 kB	1
edges/fille	3 allocs: 0.153 MB	3 allocs: 0.153 MB	1
edges/fillp	3 allocs: 0.153 MB	3 allocs: 0.153 MB	1
edges/tsume	0 allocs: 0 B	0 allocs: 0 B
edges/tsump	0 allocs: 0 B	0 allocs: 0 B
insertions/SG(n,e) Generation	0.0465 M allocs: 10.9 MB	0.0465 M allocs: 10.9 MB	0.998
parallel/egonet/twohop	10 allocs: 0.0768 MB	10 allocs: 0.0768 MB	1
parallel/egonet/vertexfunction	10 allocs: 0.0768 MB	10 allocs: 0.0768 MB	1
serial/egonet/twohop	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
serial/egonet/vertexfunction	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
traversals/digraphs/bfs_tree	2.34 k allocs: 0.113 MB	2.34 k allocs: 0.113 MB	1
traversals/digraphs/dfs_tree	2.44 k allocs: 0.118 MB	2.44 k allocs: 0.118 MB	1
traversals/graphs/bfs_tree	2.52 k allocs: 0.121 MB	2.52 k allocs: 0.121 MB	1
traversals/graphs/dfs_tree	2.63 k allocs: 0.127 MB	2.63 k allocs: 0.127 MB	1
time_to_load	0.145 k allocs: 11 kB	0.145 k allocs: 11 kB	1

[Krastanov]

This looks pretty great to me. I would suggest add IGraphs.jl and NautyGraphs.jl to the docs/Project.toml and then adding a subsection "Dispatching to algorithm implementations in wrapper packages" with a small example and then an automated listing using IGraphs.igraphalg_methods() and NautyGraphs.igraphalg_methods(). No need to hide the calls to these functions -- the user might benefit from knowing how to introspect them.

[mxhbl]

I tried something in that direction. Let me know if that works.

[Krastanov]

This looks good to me! Could you please change the using statements to imports instead?

[mxhbl]

I am a bit puzzled by the CI failures. Seems like adding NautyGraphs/IGraphs to test/Project.toml is necessary to make doctests pass. I am still a bit confused about the failure to build the docs. On my machine it works without issues.

[Krastanov]

The tests also partially build the docs so that was probably why you need them there too.

Do you happen to use a different version of Julia locally? That particular function which is failing seems to depend on unstable julia internals.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.29%. Comparing base (78818a0) to head (945cb23).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #500   +/-   ##
=======================================
  Coverage   97.29%   97.29%           
=======================================
  Files         126      126           
  Lines        7662     7662           
=======================================
  Hits         7455     7455           
  Misses        207      207           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Krastanov]

if something does not work on specific OSs or old versions of julia, we can work around it -- no need to worry about it for now

[Krastanov]

A potential fix for the method enumerator (in situations where you have more than one type parameters in your parametric type):

any(methods(f)) do m                            
    sig = m.sig                                 
    while sig isa UnionAll; sig = sig.body; end 
    any(sig.parameters) do t                    
        t isa Type && t <: NautyGraphs.NautyAlg 
    end                                         
end

[mxhbl]

Doctest pass and docs build normally now. The only issue is that, because of NautyGraphs, tests will always fail on Windows (the underlying nauty_jll cannot be loaded on Windows).