Improve documentation; fix gplothtml; add TagBot (#174)

* Improve Readme and docstring -distinguish args, kwargs -add missing kwargs * fix #166 clarify that Cairo is required to visualize in vscode * Fix #175 to enable plotting to html Checking for System OS was outdated * Document the use of gplothtml in README * Update open_file Now matches gadfly.jl (https://github.com/GiovineItalia/Gadfly.jl/blob/master/src/open_file.jl) * Minor changes: -allow gplothtml to accept same arguments as gplot -allow x/y-locs to be of different type (<: Real) * add TagBot to repo
JuliaGraphs · Jul 26, 2022 · 52f4aae · 52f4aae
1 parent 9e0d037
commit 52f4aae
Show file tree

Hide file tree

Showing 3 changed files with 100 additions and 50 deletions.
diff --git a/.github/workflows/tagbot.yml b/.github/workflows/tagbot.yml
@@ -0,0 +1,20 @@
+name: TagBot
+on:
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
+    inputs:
+      lookback:
+        default: 3
+permissions:
+  contents: write
+jobs:
+  TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: JuliaRegistries/TagBot@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ Other layout algorithms are wrapped from [NetworkX](https://github.com/networkx/
 # Getting Started
 
 From the Julia REPL the latest version can be installed with
-```{execute="false"}
+```julia
 Pkg.add("GraphPlot")
 ```
 GraphPlot is then loaded with
@@ -132,9 +132,14 @@ gplot(g, locs_x, locs_y, nodelabel=nodelabel)
 gplot(g, linetype="curve")
 ```
 
+## Show plot
+
+When using an IDE such as VSCode, `Cairo.jl` is required to visualize the plot inside the IDE.
+When using the REPL, `gplothtml` will allow displaying the plot on a browser.
+
 ## Save to figure
-```{execute="false"}
-using Cairo, Compose
+```julia
+using Compose
 # save to pdf
 draw(PDF("karate.pdf", 16cm, 16cm), gplot(g))
 # save to png
@@ -150,19 +155,34 @@ gplot(h)
 ```
 
 # Arguments
-+ `G` graph to plot
-+ `layout` Optional. layout algorithm. Currently can choose from
-[random_layout, circular_layout, spring_layout, stressmajorize_layout,
-shell_layout, spectral_layout].
-Default: `spring_layout`
-+ `nodelabel` Optional. Labels for the vertices. Default: `nothing`
-+ `nodefillc` Optional. Color to fill the nodes with.
-Default: `colorant"turquoise"`
-+ `nodestrokec` Color for the node stroke.
-Default: `nothing`
-+ `arrowlengthfrac` Fraction of line length to use for arrows.
-Set to 0 for no arrows. Default: 0 for undirected graph and 0.1 for directed graph
-+ `arrowangleoffset` angular width in radians for the arrows. Default: `π/9` (20 degrees)
++ `G` Graph to draw
++ `locs_x, locs_y` Locations of the nodes (will be normalized and centered). If not specified, will be obtained from `layout` kwarg.
+
+# Keyword Arguments
++ `layout` Layout algorithm: `random_layout`, `circular_layout`, `spring_layout`, `shell_layout`, `stressmajorize_layout`, `spectral_layout`. Default: `spring_layout`
++ `NODESIZE` Max size for the nodes. Default: `3.0/sqrt(N)`
++ `nodesize` Relative size for the nodes, can be a Vector. Default: `1.0`
++ `nodelabel` Labels for the vertices, a Vector or nothing. Default: `nothing`
++ `nodelabelc` Color for the node labels, can be a Vector. Default: `colorant"black"`
++ `nodelabeldist` Distances for the node labels from center of nodes. Default: `0.0`
++ `nodelabelangleoffset` Angle offset for the node labels. Default: `π/4.0`
++ `NODELABELSIZE` Largest fontsize for the vertice labels. Default: `4.0`
++ `nodelabelsize` Relative fontsize for the vertice labels, can be a Vector. Default: `1.0`
++ `nodefillc` Color to fill the nodes with, can be a Vector. Default: `colorant"turquoise"`
++ `nodestrokec` Color for the nodes stroke, can be a Vector. Default: `nothing`
++ `nodestrokelw` Line width for the nodes stroke, can be a Vector. Default: `0.0`
++ `edgelabel` Labels for the edges, a Vector or nothing. Default: `[]`
++ `edgelabelc` Color for the edge labels, can be a Vector. Default: `colorant"black"`
++ `edgelabeldistx, edgelabeldisty` Distance for the edge label from center of edge. Default: `0.0`
++ `EDGELABELSIZE` Largest fontsize for the edge labels. Default: `4.0`
++ `edgelabelsize` Relative fontsize for the edge labels, can be a Vector. Default: `1.0`
++ `EDGELINEWIDTH` Max line width for the edges. Default: `0.25/sqrt(N)`
++ `edgelinewidth` Relative line width for the edges, can be a Vector. Default: `1.0`
++ `edgestrokec` Color for the edge strokes, can be a Vector. Default: `colorant"lightgray"`
++ `arrowlengthfrac` Fraction of line length to use for arrows. Equal to 0 for undirected graphs. Default: `0.1` for the directed graphs
++ `arrowangleoffset` Angular width in radians for the arrows. Default: `π/9 (20 degrees)`
++ `linetype` Type of line used for edges ("straight", "curve"). Default: "straight"
++ `outangle` Angular width in radians for the edges (only used if `linetype = "curve`). Default: `π/5 (36 degrees)`
 
 # Reporting Bugs
 

diff --git a/src/plot.jl b/src/plot.jl
@@ -10,83 +10,93 @@ a Compose tree of the graph layout
 `G`
 Graph to draw
 
+`locs_x, locs_y`
+Locations of the nodes. Can be any units you want,
+but will be normalized and centered anyway. If not provided, will
+be obtained from `layout` kwarg.
+
+**Keyword Arguments**
+
 `layout`
-Optional. Layout algorithm. Currently can be one of [`random_layout`,
+Layout algorithm. Currently can be one of [`random_layout`,
 `circular_layout`, `spring_layout`, `shell_layout`, `stressmajorize_layout`,
 `spectral_layout`].
 Default: `spring_layout`
 
-`locs_x, locs_y`
-Locations of the nodes. Can be any units you want,
-but will be normalized and centered anyway
-
 `NODESIZE`
-Optional. Max size for the nodes. Default: `3.0/sqrt(N)`
+Max size for the nodes. Default: `3.0/sqrt(N)`
 
 `nodesize`
-Optional. Relative size for the nodes, can be a Vector. Default: `1.0`
+Relative size for the nodes, can be a Vector. Default: `1.0`
 
 `nodelabel`
-Optional. Labels for the vertices, a Vector or nothing. Default: `nothing`
+Labels for the vertices, a Vector or nothing. Default: `nothing`
 
 `nodelabelc`
-Optional. Color for the node labels, can be a Vector. Default: `colorant"black"`
+Color for the node labels, can be a Vector. Default: `colorant"black"`
 
 `nodelabeldist`
-Optional. Distances for the node labels from center of nodes. Default: `0.0`
+Distances for the node labels from center of nodes. Default: `0.0`
 
 `nodelabelangleoffset`
-Optional. Angle offset for the node labels. Default: `π/4.0`
+Angle offset for the node labels. Default: `π/4.0`
 
 `NODELABELSIZE`
-Optional. Largest fontsize for the vertice labels. Default: `4.0`
+Largest fontsize for the vertice labels. Default: `4.0`
 
 `nodelabelsize`
-Optional. Relative fontsize for the vertice labels, can be a Vector. Default: `1.0`
+Relative fontsize for the vertice labels, can be a Vector. Default: `1.0`
 
 `nodefillc`
-Optional. Color to fill the nodes with, can be a Vector. Default: `colorant"turquoise"`
+Color to fill the nodes with, can be a Vector. Default: `colorant"turquoise"`
 
 `nodestrokec`
-Optional. Color for the nodes stroke, can be a Vector. Default: `nothing`
+Color for the nodes stroke, can be a Vector. Default: `nothing`
 
 `nodestrokelw`
-Optional. Line width for the nodes stroke, can be a Vector. Default: `0.0`
+Line width for the nodes stroke, can be a Vector. Default: `0.0`
 
 `edgelabel`
-Optional. Labels for the edges, a Vector or nothing. Default: `[]`
+Labels for the edges, a Vector or nothing. Default: `[]`
 
 `edgelabelc`
-Optional. Color for the edge labels, can be a Vector. Default: `colorant"black"`
+Color for the edge labels, can be a Vector. Default: `colorant"black"`
 
 `edgelabeldistx, edgelabeldisty`
-Optional. Distance for the edge label from center of edge. Default: `0.0`
+Distance for the edge label from center of edge. Default: `0.0`
 
 `EDGELABELSIZE`
-Optional. Largest fontsize for the edge labels. Default: `4.0`
+Largest fontsize for the edge labels. Default: `4.0`
 
 `edgelabelsize`
-Optional. Relative fontsize for the edge labels, can be a Vector. Default: `1.0`
+Relative fontsize for the edge labels, can be a Vector. Default: `1.0`
 
 `EDGELINEWIDTH`
-Optional. Max line width for the edges. Default: `0.25/sqrt(N)`
+Max line width for the edges. Default: `0.25/sqrt(N)`
 
 `edgelinewidth`
-Optional. Relative line width for the edges, can be a Vector. Default: `1.0`
+Relative line width for the edges, can be a Vector. Default: `1.0`
 
 `edgestrokec`
-Optional. Color for the edge strokes, can be a Vector. Default: `colorant"lightgray"`
+Color for the edge strokes, can be a Vector. Default: `colorant"lightgray"`
 
 `arrowlengthfrac`
-Optional. Fraction of line length to use for arrows.
+Fraction of line length to use for arrows.
 Equal to 0 for undirected graphs. Default: `0.1` for the directed graphs
 
 `arrowangleoffset`
-Optional. Angular width in radians for the arrows. Default: `π/9 (20 degrees)`
+Angular width in radians for the arrows. Default: `π/9 (20 degrees)`
+
+`linetype`
+Type of line used for edges ("straight", "curve"). Default: "straight"
+
+`outangle`
+Angular width in radians for the edges (only used if `linetype = "curve`). 
+Default: `π/5 (36 degrees)`
 
 """
 function gplot(g::AbstractGraph{T},
-    locs_x_in::Vector{R}, locs_y_in::Vector{R};
+    locs_x_in::Vector{R1}, locs_y_in::Vector{R2};
     nodelabel = nothing,
     nodelabelc = colorant"black",
     nodelabelsize = 1.0,
@@ -108,9 +118,9 @@ function gplot(g::AbstractGraph{T},
     nodestrokec = nothing,
     nodestrokelw = 0.0,
     arrowlengthfrac = is_directed(g) ? 0.1 : 0.0,
-    arrowangleoffset = π / 9.0,
+    arrowangleoffset = π / 9,
     linetype = "straight",
-    outangle = pi/5) where {T <:Integer, R <: Real}
+    outangle = π / 5) where {T <:Integer, R1 <: Real, R2 <: Real}
 
     length(locs_x_in) != length(locs_y_in) && error("Vectors must be same length")
     N = nv(g)
@@ -231,25 +241,25 @@ end
 
 # take from [Gadfly.jl](https://github.com/dcjones/Gadfly.jl)
 function open_file(filename)
-    if Sys.KERNEL == :Darwin
+    if Sys.isapple() #apple
         run(`open $(filename)`)
-    elseif Sys.KERNEL == :Linux || Sys.KERNEL == :FreeBSD
+    elseif Sys.islinux() || Sys.isbsd() #linux
         run(`xdg-open $(filename)`)
-    elseif Sys.KERNEL == :Windows
+    elseif Sys.iswindows() #windows
         run(`$(ENV["COMSPEC"]) /c start $(filename)`)
     else
         @warn("Showing plots is not supported on OS $(string(Sys.KERNEL))")
     end
 end
 
 # taken from [Gadfly.jl](https://github.com/dcjones/Gadfly.jl)
-function gplothtml(g; layout::Function=spring_layout, keyargs...)
+function gplothtml(args...; keyargs...)
     filename = string(tempname(), ".html")
     output = open(filename, "w")
 
     plot_output = IOBuffer()
     draw(SVGJS(plot_output, Compose.default_graphic_width,
-               Compose.default_graphic_width, false), gplot(g, layout(g)...; keyargs...))
+               Compose.default_graphic_width, false), gplot(args...; keyargs...))
     plotsvg = String(take!(plot_output))
 
     write(output,