Is there a function docs that will open up the documentation of a package in a new browser window?
docs(DataFrames)
Goes here
It would maybe be a nice feature. Given that so many packages have their Docs as part of the same git repo, the problem of outdated links might not be so bad?
I don’t think this exist, but something like it would be nice. Something that you can already do:
"""
MyPackage
This is my package, docs are here: www.my-package-docs.com
"""
module MyPackage
...
end
which would then show up in help via ?MyPackage. Since most terminals have clickable links this will be very convenient. Not many packages document their module like this though, but maybe you can contribute something like that to the packages you use?
Thanks for the reply. Yes, I think I might do that.
Is documentation online, or even documentation as part of the git-repo of the package a requirement for package registration?
No, I don’t think so, but it is recommended. For some packages the README is documentation enough so those packages can point to that.
Yeah that is my impression. If this is ever standardized it would be cool to have the git-repo as a fall-back.
I was working with some new packages in R yesterday and I really appreciated being able to write help(thispackage) and have it immediately open up a detailed man page. Especially if you have no idea what even the function names of that package are. It’s a good way to orient oneself.
Stata has the same requirement, where any package on ssc must have a full man page, and I’ve also found that helpful working with new packages.
Readmes of git repos are always included in a package, it would be cool if there were a function that just pulled up the readme of a package. Plus this could be a package and not require PRs to the packages themselves.
It looks like this function readme existed at some point according to this source from 2015.
can’t find where it went, though. It seems it was in Base at one point.
Ah, found it:
https://github.com/JuliaLang/julia/pull/25772
I implemented something that is IMO better than the old readme and license functions: https://github.com/JuliaDocs/DocStringExtensions.jl/pull/68
With that PR you can simply add $(README) and/or $(LICENSE) to the docstring, and it will show up in help. Example:
"""
$(README)
$(LICENSE)
"""
module TestPackage
using DocStringExtensions
end
with help output:
julia> using TestPackage
help?> TestPackage
search: TestPackage
Hello from README.md.
Hello from LICENSE.md.
Ah that’s awesome, thanks!
The old readme function seemed nice though because it required no effort on the package developer’s part, other than maintaining a readme file, so I think there is still a use-case for the original readme function.
Yea, you are right. I forgot that that function was called automatically in case there were no docs found.
It used to be the case that typing
?Package
displayed the docstring or readme for the package. Last time I tried, that functionality seemed to have been removed. Maybe we should put it back?
Modules still get docstrings, it’s just that package authors don’t always write them, which makes sense, because the readme is a de-facto “welcome to this package” document, or the documentation itself.
I define this macro. It’s useful sometimes:
readreadme(mod::Module) = readreadme(Base.PkgId(mod))
function readreadme(pkg::Base.PkgId)
path = joinpath(dirname(dirname(Base.locate_package(pkg))), "README.md")
return Markdown.parse_file(path)
end
"""
@readreadme module
Read README.md of `module`.
"""
macro readreadme(ex)
quote
mod = try
$(esc(ex))
catch err
err isa UndefVarError || rethrow()
nothing
end
if mod === nothing
readreadme(Base.identify_package($(string(ex))))
else
readreadme(mod)
end
end
end
Yeah this is great. And something like Atom or IJulia could render that as html directly, too.