Correct tests and docs

README.md

@@ -2,20 +2,68 @@
 
 [![Build Status](https://github.com/simonp0420/PkgOnlineHelp.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/simonp0420/PkgOnlineHelp.jl/actions/workflows/CI.yml?query=branch%3Amain)
 
-A small package to help users navigate to Julia package home repositories. The two (identical) functions exported by this package are `pkg_site` and `package_site`.
+A package to help users quickly navigate to Julia package home repositories and documentation sites.
 
-    `url = package_site(pkgname::AbstractString; autoopen=true)`
+# Installation
 
-    `url = pkg_site(pkgname::AbstractString; autoopen=true)`
+```julia
+julia> import Pkg
+
+julia> Pkg.add("PkgOnlineHelp")
+```
+
+# Usage
+
+The main convenience macro is `@docs`.  As an example of usage:
+
+```julia
+julia> using PkgOnlineHelp  # If not included in your startup.jl
+
+julia> @docs StaticArrays
+"https://github.com/JuliaArrays/StaticArrays.jl.git"
+```
+
+The `StaticArrays` repo site is returned and opened in the browser.  In this example
+the user had not previously entered the actual documentation site via a prior call
+to `add_pkg_docs`. The repo site was found by searching through all Julia registries
+in `DEPOT_PATH`. 
 
+`@docs` can also be used to access unregistered packages or even arbitrary web sites.
+Suppose you wish to have rapid access to the portion of the Julia documentation discussing
+macros.  Then you would (one time only) enter the following at the Julia prompt:
+```julia
+julia> add_pkg_docs("macros", "https://docs.julialang.org/en/v1/manual/metaprogramming/#man-macros")
+```
+Later in this Julia session, or in any future session, the site can be quickly opened by entering
+```julia
+julia> @docs macros
+```
+Of course, this example assumes that `using PkgOnlineHelp` has already been entered.  
+For convenience, you may wish to include this statement in your `startup.jl` file.
+
+The contents of the `PkgOnlineHelp` database can be shown by typing `list_pkg_docs()`
+at the REPL prompt. Items can be removed using, e.g. `remove_pkg_docs("macros")`.
+
+# Other Exported Functions
+
+## `pkg_site`
+```julia
+    url = pkg_site(pkgname::AbstractString; autoopen=true)
+```
 
 Attempt to find the URL of a package's home repository, by searching through the registries in `DEPOT_PATH`.  If `autoopen` is `true` (default), then open the URL using the default browser.
-# Example
+### Example
 ```julia
 julia> package_site("StaticArrays")
 "https://github.com/JuliaArrays/StaticArrays.jl.git"
 ```
 
 In this example the web site is also opened in the user's browser.
 
+## `pkg_docs_site`
+```julia
+    url = pkg_docs_site(pkgname::AbstractString, autoopen==true)
+```
+This is the function invoked by the `@docs` macro.  See the discussion
+above re `@docs`.
 

src/PkgOnlineHelp.jl

@@ -1,7 +1,7 @@
 """
 A package to help users navigate to Julia package home repositories and documentation
 sites. See help for exported functions `pkg_site`, `add_pkg_docs`, `remove_pkg_docs`, 
-`list_pkg_docs`, `pkg_doc_site`, and the convenience macro `@docs`.
+`list_pkg_docs`, `pkg_docs_site`, and the convenience macro `@docs`.
 """
 module PkgOnlineHelp
 
@@ -31,15 +31,15 @@ function pkg_site(pkgname::AbstractString; autoopen = true)
     for depot in DEPOT_PATH
         isdir(joinpath(depot, "registries")) || continue
         for r in readdir(joinpath(depot, "registries"))
-            file = joinpath(depot, "registries", r, pkgname[1:1], pkgname, "Package.toml")
+            file = joinpath(depot, "registries", r, uppercase(pkgname[1:1]), 
+            pkgname, "Package.toml")
             !isfile(file) && continue
             repoline = readlines(file)[3]
             url = TOML.parse(repoline)["repo"]
             autoopen && DefaultApplication.open(url)
             return url
         end
     end
-    println("Package $pkgname not found in available registries")
     return nothing
 end
 
@@ -97,9 +97,9 @@ function remove_pkg_docs(package::AbstractString)
 end
 
 """
-    list_pkg_docs(package::AbstractString)
+    list_pkg_docs(io::IO=stdout)
 
-Remove an entry for a package's documentation web site from the local database.
+Print out the documentation sites stored in the `PkgOnlineHelp` database to IO stream `io`.
 """
 function list_pkg_docs(io::IO=stdout)
     pkgdict, tomlfile = _get_pkgdict()
@@ -108,7 +108,7 @@ function list_pkg_docs(io::IO=stdout)
 end
 
 """
-    url = pkg_docs_site(package::String, autoopen=true)
+    url = pkg_docs_site(package::String; autoopen=true)
 
 Attempt to find the URL of a package's documentation site by searching 
 through the local database established by previous calls to `add_pkg_docs`.
@@ -133,14 +133,14 @@ julia> pkg_docs_site("PSSFSS")
 
 In addition, the site is opened in the user's default browser.
 """
-function pkg_docs_site(package::String, autoopen=true)
+function pkg_docs_site(package::String; autoopen=true)
     pkgdict, _ = _get_pkgdict()
     if haskey(pkgdict, package)
         url = pkgdict[package]
     else
-        url = pkg_site(package, autoopen=false)
+        url = pkg_site(package; autoopen=false)
     end
-    autoopen && DefaultApplication.open(url)
+    autoopen && !isnothing(url) && DefaultApplication.open(url)
     return url
 end
 
@@ -151,22 +151,39 @@ Retrieve the URL of the package's documentation site if previously recorded via
 `add_pkg_docs` or to the package's repository otherwise.  Open the URL in the user's 
 default browser.
 
-# Example
+# Examples
+
 ```
 julia> using PkgOnlineHelp
 
 julia> @docs StaticArrays
 "https://github.com/JuliaArrays/StaticArrays.jl.git"
+```
 
 The `StaticArrays` repo site is returned and opened in the browser.  In this example
 the user had not previously entered the actual documentation site via a prior call
-to `add_pkg_docs`. 
+to `add_pkg_docs`. The repo site was found by searching through all Julia registries
+in `DEPOT_PATH`. 
+
+`@docs` can also be used to access unregistered packages or even arbitrary web sites.
+Suppose you wish to have rapid access to the portion of the Julia documentation discussing
+macros.  Then you would (one time only) enter the following at the Julia prompt:
+```julia
+julia> add_pkg_docs("macros", "https://docs.julialang.org/en/v1/manual/metaprogramming/#man-macros")
+```
+Later in this Julia session, or in any future session, the site can be quickly opened by entering
+```julia
+julia> @docs macros
+```
+Of course, this example assumes that `using PkgOnlineHelp` has already been entered.  
+For convenience, you may wish to include this statement in your `startup.jl` file.
+
 
 # See Also
 `add_pkg_docs`, `remove_pkg_docs`, `list_pkg_docs`, `pkg_site`
 """
 macro docs(package)
-    :(pkg_docs_site($(string(package))))
+    esc(:(pkg_docs_site($(string(package)))))
 end
 
 end

test/runtests.jl

@@ -2,7 +2,39 @@ using PkgOnlineHelp
 using Test
 
 @testset "PkgOnlineHelp.jl" begin
-    @test package_site("StaticArrays"; autoopen=false) == "https://github.com/JuliaArrays/StaticArrays.jl.git"
-    @test package_site("StaticArrays.jl"; autoopen=false) == "https://github.com/JuliaArrays/StaticArrays.jl.git"
-    @test package_site("StaticVectors"; autoopen=false) == nothing
+    @test pkg_site("StaticArrays"; autoopen=false) == "https://github.com/JuliaArrays/StaticArrays.jl.git"
+    @test pkg_site("StaticArrays.jl"; autoopen=false) == "https://github.com/JuliaArrays/StaticArrays.jl.git"
+    @test pkg_site("StaticCling"; autoopen=false) == nothing
+    @test @macroexpand(@docs(StaticArrays)) == :(pkg_docs_site("StaticArrays"))
+    @test pkg_site("StaticArrays", autoopen=false) == "https://github.com/JuliaArrays/StaticArrays.jl.git"
+
+
+    function _get_docs()
+        iob = IOBuffer()
+        list_pkg_docs(iob)
+        docs = split(read(seekstart(iob), String))
+    end    
+
+    newpkg = "testxyznonsense"
+    newpkg_site = "http://more_nonsense"
+    newpkg_site_test = "\"" * newpkg_site * "\""
+
+    docs = _get_docs()
+    @test newpkg ∉ docs
+    @test newpkg_site_test ∉ docs
+
+    add_pkg_docs(newpkg, newpkg_site)
+    docs = _get_docs()
+
+    @test newpkg ∈ docs
+    @test newpkg_site_test ∈ docs
+    @test pkg_docs_site(newpkg; autoopen=false) == newpkg_site
+
+    remove_pkg_docs(newpkg)
+    docs = _get_docs()
+
+    @test newpkg ∉ docs
+    @test newpkg_site_test ∉ docs
+    @test pkg_docs_site(newpkg; autoopen=false) == nothing
+
 end