From fc03a9422ade8b99e4ba392d12f39737c4d3671a Mon Sep 17 00:00:00 2001 From: Ian Date: Mon, 4 Jan 2021 15:47:08 -0500 Subject: [PATCH 1/9] print available readme if no docstring for module --- stdlib/REPL/src/docview.jl | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 9394c7f22ba68..6cdbf90e24d41 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -243,10 +243,12 @@ end function summarize(binding::Binding, sig) io = IOBuffer() - println(io, "No documentation found.\n") if defined(binding) - summarize(io, resolve(binding), binding) + binding_res = resolve(binding) + !isa(binding_res, Module) && println(io, "No documentation found.\n") + summarize(io, binding_res, binding) else + println(io, "No documentation found.\n") println(io, "Binding `", binding, "` does not exist.") end md = Markdown.parse(seekstart(io)) @@ -299,8 +301,27 @@ function summarize(io::IO, T::DataType, binding::Binding) end end +function find_readme(m::Module)::Union{String, Nothing} + path = dirname(pathof(m)) + while true + for readme in ["README.md", "readme.md", "Readme.md", "ReadMe.md"] + readme_path = joinpath(path, readme) + if isfile(readme_path) + return readme_path + end + end + path = dirname(path) # work up through nested modules + Base.endswith(path, "src") && break + end + return nothing +end function summarize(io::IO, m::Module, binding::Binding) println(io, "No docstring found for module `", m, "`.\n") + readme_path = find_readme(m) + if !isnothing(readme_path) + readme_string = read(readme_path, String) + println(io, "Displaying the contents of `$(readme_path)`:\n\n", readme_string) + end end function summarize(io::IO, @nospecialize(T), binding::Binding) From b46013c8333a6af663529b1ca0c40426356f4158 Mon Sep 17 00:00:00 2001 From: Ian Date: Mon, 4 Jan 2021 16:04:48 -0500 Subject: [PATCH 2/9] tweak search & print --- stdlib/REPL/src/docview.jl | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 6cdbf90e24d41..8f85aa444656d 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -303,6 +303,7 @@ end function find_readme(m::Module)::Union{String, Nothing} path = dirname(pathof(m)) + top_path = pkgdir(m) while true for readme in ["README.md", "readme.md", "Readme.md", "ReadMe.md"] readme_path = joinpath(path, readme) @@ -310,17 +311,19 @@ function find_readme(m::Module)::Union{String, Nothing} return readme_path end end + path == top_path && break # go no further than pkgdir path = dirname(path) # work up through nested modules - Base.endswith(path, "src") && break end return nothing end function summarize(io::IO, m::Module, binding::Binding) - println(io, "No docstring found for module `", m, "`.\n") readme_path = find_readme(m) if !isnothing(readme_path) + println(io, "No docstring found for module `", m, "`.\n") readme_string = read(readme_path, String) println(io, "Displaying the contents of `$(readme_path)`:\n\n", readme_string) + else + println(io, "No docstring or readme found for module `", m, "`.\n") end end From 6cfc39c8f3ad24b0bd7bdcca22b057f7a5b0d1d6 Mon Sep 17 00:00:00 2001 From: Ian Date: Mon, 4 Jan 2021 18:03:26 -0500 Subject: [PATCH 3/9] handle pathless modules --- stdlib/REPL/src/docview.jl | 1 + 1 file changed, 1 insertion(+) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 8f85aa444656d..784e7f8c87de6 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -302,6 +302,7 @@ function summarize(io::IO, T::DataType, binding::Binding) end function find_readme(m::Module)::Union{String, Nothing} + isnothing(pathof(m)) && return nothing path = dirname(pathof(m)) top_path = pkgdir(m) while true From 25a2569db2503513a255d65127ed33df73d6217a Mon Sep 17 00:00:00 2001 From: Ian Date: Mon, 4 Jan 2021 23:37:11 -0500 Subject: [PATCH 4/9] limit readme print to first 200 lines --- stdlib/REPL/src/docview.jl | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 784e7f8c87de6..1643461becd84 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -317,12 +317,14 @@ function find_readme(m::Module)::Union{String, Nothing} end return nothing end -function summarize(io::IO, m::Module, binding::Binding) +function summarize(io::IO, m::Module, binding::Binding; nlines::Int = 200) readme_path = find_readme(m) if !isnothing(readme_path) println(io, "No docstring found for module `", m, "`.\n") - readme_string = read(readme_path, String) - println(io, "Displaying the contents of `$(readme_path)`:\n\n", readme_string) + readme_lines = readlines(readme_path) + println(io, "Displaying the contents of `$(readme_path)`:\n\n") + [println(io, line) for line in first(readme_lines, nlines)] + length(readme_lines) > nlines && println(io, "[output truncated to first $nlines lines]") else println(io, "No docstring or readme found for module `", m, "`.\n") end From c27d10c93a14feacc2f77a3b1542850916401e92 Mon Sep 17 00:00:00 2001 From: Ian Date: Tue, 5 Jan 2021 11:17:30 -0500 Subject: [PATCH 5/9] review changes --- stdlib/REPL/src/docview.jl | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 1643461becd84..1793f8aaf8b9b 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -306,11 +306,9 @@ function find_readme(m::Module)::Union{String, Nothing} path = dirname(pathof(m)) top_path = pkgdir(m) while true - for readme in ["README.md", "readme.md", "Readme.md", "ReadMe.md"] - readme_path = joinpath(path, readme) - if isfile(readme_path) - return readme_path - end + for file in readdir(path; join=true, sort=true) + isfile(file) && (basename(lowercase(file)) in ["readme.md", "readme"]) || continue + return file end path == top_path && break # go no further than pkgdir path = dirname(path) # work up through nested modules @@ -320,13 +318,15 @@ end function summarize(io::IO, m::Module, binding::Binding; nlines::Int = 200) readme_path = find_readme(m) if !isnothing(readme_path) - println(io, "No docstring found for module `", m, "`.\n") + println(io, "No docstring found for module `$m`.\n") readme_lines = readlines(readme_path) println(io, "Displaying the contents of `$(readme_path)`:\n\n") - [println(io, line) for line in first(readme_lines, nlines)] - length(readme_lines) > nlines && println(io, "[output truncated to first $nlines lines]") + for line in first(readme_lines, nlines) + println(io, line) + end + length(readme_lines) > nlines && println(io, "\n[output truncated to first $nlines lines]") else - println(io, "No docstring or readme found for module `", m, "`.\n") + println(io, "No docstring or readme file found for module `$m`.\n") end end From 3f76282347b89837512edcd73a619f2019f637bd Mon Sep 17 00:00:00 2001 From: Ian Date: Tue, 5 Jan 2021 16:10:01 -0500 Subject: [PATCH 6/9] print message on single line --- stdlib/REPL/src/docview.jl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 1793f8aaf8b9b..d7da76b4c48ce 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -318,9 +318,10 @@ end function summarize(io::IO, m::Module, binding::Binding; nlines::Int = 200) readme_path = find_readme(m) if !isnothing(readme_path) - println(io, "No docstring found for module `$m`.\n") + print(io, "No docstring found for module `$m`.") readme_lines = readlines(readme_path) - println(io, "Displaying the contents of `$(readme_path)`:\n\n") + isempty(readme_lines) && return # don't say we are going to print empty file + println(io, " Displaying the contents of `$(readme_path)`:\n\n") for line in first(readme_lines, nlines) println(io, line) end From 14d94165087f0a6a732a36478d81f97068b2c873 Mon Sep 17 00:00:00 2001 From: Ian Date: Tue, 5 Jan 2021 16:49:51 -0500 Subject: [PATCH 7/9] handle modules in sysimage that are missing src files --- stdlib/REPL/src/docview.jl | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index d7da76b4c48ce..3d4abc30f6cde 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -302,8 +302,10 @@ function summarize(io::IO, T::DataType, binding::Binding) end function find_readme(m::Module)::Union{String, Nothing} - isnothing(pathof(m)) && return nothing - path = dirname(pathof(m)) + mpath = pathof(m) + isnothing(mpath) && return nothing + !isfile(mpath) && return nothing # modules in sysimage, where src files are omitted + path = dirname(mpath) top_path = pkgdir(m) while true for file in readdir(path; join=true, sort=true) From d78e383b13c81554eb7ec401b4392da5c8e92a13 Mon Sep 17 00:00:00 2001 From: Ian Date: Sun, 4 Apr 2021 14:16:14 -0400 Subject: [PATCH 8/9] tweak formatting --- stdlib/REPL/src/docview.jl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/stdlib/REPL/src/docview.jl b/stdlib/REPL/src/docview.jl index 762a5e996b49d..d6b523160da1e 100644 --- a/stdlib/REPL/src/docview.jl +++ b/stdlib/REPL/src/docview.jl @@ -342,15 +342,15 @@ function summarize(io::IO, m::Module, binding::Binding; nlines::Int = 200) if isempty(exports) println(io, "Module does not export any names.") else - println(io, "# Exported names:") + println(io, "# Exported names") print(io, " `") join(io, exports, "`, `") - println(io, "`") + println(io, "`\n") end if !isnothing(readme_path) readme_lines = readlines(readme_path) isempty(readme_lines) && return # don't say we are going to print empty file - println(io, " Displaying the contents of `$(readme_path)`:\n\n") + println(io, "# Displaying contents of readme found at `$(readme_path)`") for line in first(readme_lines, nlines) println(io, line) end From eaf307d55b9549dd9c8fc5c597476de81ec09175 Mon Sep 17 00:00:00 2001 From: Ian Date: Tue, 6 Apr 2021 15:11:37 -0400 Subject: [PATCH 9/9] fix docstring test --- test/docs.jl | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/test/docs.jl b/test/docs.jl index da7a6f01f03e0..c7652bd73920e 100644 --- a/test/docs.jl +++ b/test/docs.jl @@ -863,11 +863,9 @@ undocumented(x,y) = 3 end # module doc_str = Markdown.parse(""" -No documentation found. - -No docstring found for module `$(curmod_prefix)Undocumented`. +No docstring or readme file found for module `$(curmod_prefix)Undocumented`. -# Exported names: +# Exported names `A`, `B`, `C`, `at0`, `pt2` """)