Rename & export end-user API functions (PkgGraph.open → `depgraph_w…

…eb`)

Closes #74 and #67

Changelog.md

@@ -34,9 +34,12 @@ The version numbers roughly follow <a href="https://semver.org">SemVer</a>
 Possible categories: [Added, Changed, Fixed, Removed, Security,
                       Deprecated (for soon-to-be removed features)]
 -->
+- Rename and export the end-user API functions:
+  - `PkgGraph.open` → `depgraph_web`
+  - `PkgGraph.create` → `depgraph_image`
 - Keyword `mode=:dark` renamed to `dark=true` (default is still
   light-mode i.e. `dark=false`)
-- `PkgGraph.create`: default background colour is now `:white` if 
+- `depgraph_image`: default background colour is now `:white` if 
   `fmt=:png` (which is the default format)
   - Why?\
     (1). PNG is default, because the default Windows image viewer allows

ReadMe.md

@@ -21,7 +21,7 @@ Small tool to visualize the dependency graph of a Julia package.
 ```julia
 julia> using PkgGraph
 
-julia> PkgGraph.open(:Unitful)
+julia> depgraph_web(:Unitful)
 ```
 This will open the browser to [this url][dotlink], which renders something like the following:
 
@@ -44,7 +44,7 @@ To filter out binary dependencies ([JLL packages]) or packages from the Julia st
 
 If you are offline and have [Graphviz `dot`](https://graphviz.org) installed on your PATH, you can use something like
 ```julia
-julia> PkgGraph.create(:Unitful, ".", fmt=:svg)
+julia> depgraph_image(:Unitful, ".", fmt=:svg)
 ```
 This will call `dot` to create an SVG image in the current directory (`"."`), and will open it with your default image viewer.
 

docs/scripts/update_imgs_and_url.jl

@@ -12,9 +12,9 @@ cd("../..")
 
 Pkg.activate("test")
 
-PkgGraph.create("Unitful", "docs/img/", fmt=:png, open=false)
-PkgGraph.create("Unitful", "docs/img/", fmt=:svg, open=false)
-PkgGraph.create("Test", "docs/img/", fmt=:svg, open=false)
+depgraph_image("Unitful", "docs/img/", fmt=:png, open=false)
+depgraph_image("Unitful", "docs/img/", fmt=:svg, open=false)
+depgraph_image("Test", "docs/img/", fmt=:svg, open=false)
 
 f = "ReadMe.md"
 md = read(f, String)

docs/src/bg/usage-tips.md

@@ -21,13 +21,13 @@ this, as it provides a GUI interface for adding new nodes and changing styles.
 and [its repository][gh] is receiving active updates at the time of writing).
 
 You can use Magnus's app by providing the following as keyword argument to
-[`PkgGraph.open`](@ref):
+[`depgraph_web`](@ref):
 
 ```jldoctest; setup=:( using PkgGraph )
 julia> base_url = PkgGraph.webapps[2]
 "http://magjac.com/graphviz-visual-editor/?dot="
 
-julia> # PkgGraph.open(:Test; base_url)
+julia> # depgraph_web(:Test; base_url)
 ```
 
 [mj]: http://magjac.com/graphviz-visual-editor

docs/src/ref/end-user.md

@@ -11,10 +11,10 @@ PkgGraph
 
 ## Online
 ```@docs
-PkgGraph.open
+depgraph_web
 ```
 
 ## Local
 ```@docs
-PkgGraph.create
+depgraph_image
 ```

src/PkgGraph.jl

@@ -1,10 +1,8 @@
 """
 Visualize the dependency graph of a Julia package.
 
-Use [`PkgGraph.open`](@ref) to view the graph in the browser,
-or [`PkgGraph.create`](@ref) to generate an image locally.
-
-(Note that these functions are not exported).
+Use [`depgraph_web`](@ref) to view the graph in the browser,
+or [`depgraph_image`](@ref) to generate an image locally.
 """
 module PkgGraph
 
@@ -30,7 +28,7 @@ include("includes/dotcommand.jl")
 include("includes/webapps.jl")
 include("includes/enduser.jl")
 
-# No package exports (no namespace pollution)
+export depgraph_web, depgraph_image
 
 
 end # module

src/includes/enduser.jl

@@ -1,13 +1,13 @@
 
 """
-    open(pkgname, base_url = first(webapps); kw...)
+    depgraph_web(pkgname, base_url = first(webapps); kw...)
 
 Open the browser to an image of `pkgname`'s dependency graph.
 
-See [`url`](@ref) for more on `base_url`, and for possible keyword
-arguments see [`depgraph`](@ref) and [`to_dot_str`](@ref) .
+See [`url`](@ref) for more on `base_url`. Keyword arguments are passed
+on to [`depgraph`](@ref) and [`to_dot_str`](@ref).
 """
-function open(pkgname, base_url = first(webapps); dryrun = false, kw...)
+function depgraph_web(pkgname, base_url=first(webapps); dryrun=false, kw...)
     dotstr = depgraph_as_dotstr(pkgname; kw...)
     link = url(dotstr, base_url)
     if !dryrun
@@ -20,7 +20,7 @@ function open(pkgname, base_url = first(webapps); dryrun = false, kw...)
 end
 
 """
-    create(pkgname, dir = tempdir(); fmt = :png, open = true, kw...)
+    depgraph_image(pkgname, dir = tempdir(); fmt = :png, open = true, kw...)
 
 Render the dependency graph of the given package as an image in `dir`,
 and open it with your default image viewer. Uses the external program
@@ -34,10 +34,18 @@ light and dark-mode CSS.
 To only create the image, without automatically opening it, pass
 `open = false`.
 
-See [`depgraph`](@ref) and [`to_dot_str`](@ref) for more keyword
-arguments.
+Other keyword arguments are passed on to [`depgraph`](@ref) and
+[`to_dot_str`](@ref).
 """
-function create(pkgname, dir=tempdir(); fmt=:png, bg=bg(fmt), open=true, dryrun=false, kw...)
+function depgraph_image(
+    pkgname,
+    dir    = tempdir();
+    fmt    = :png,
+    bg     = bg(fmt),
+    open   = true,
+    dryrun = false,
+    kw...
+)
     if !is_dot_available() && !dryrun
         error("`dot` program not found on `PATH`. Get it at https://graphviz.org/download/")
     end

test/unit/PkgGraph.jl

@@ -23,8 +23,8 @@ using Test
 
     @testset "end-user" begin
 
-        @test isnothing(PkgGraph.open("Test", dryrun = true))
-        @test isnothing(PkgGraph.create("Test", dryrun = true))
-        @test isnothing(PkgGraph.create("PyPlot", dryrun = true))
+        @test isnothing(depgraph_web("Test", dryrun = true))
+        @test isnothing(depgraph_image("Test", dryrun = true))
+        @test isnothing(depgraph_image("PyPlot", dryrun = true))
     end
 end