Package-level man pages

[hrbrmstr]

One of the things I've needed to apologize for (when teaching) is the lack of consistency in "package-level man pages". For example, you can ?httr but not ?rvest.

I'm suggesting a project where we:

• find all the gh sites for CRAN pkgs that have no pkg man page
• add a basic one to each of them (possibly from the README.Rmd
• file a PR that includes a well-written explanation why we did this
• perhaps find a way to automate ^^

[jennybc]

Incidentally, this is often the easiest way to get any help page up for a package, so you can then click on the link to the index. This is why I like them.

BTW why is it so hard to visit a package's index? I'm also happy to be told some trick I'm missing.

[hrbrmstr]

https://www.r-project.org/help.html ;-)

help(package="PACKAGENAME")

but that's a bit to type. hence this suggestion.

I wonder if we shld couple this suggestion with @jennybc's twitter suggestion to add github URL and issue links to all github'd CRAN pkgs?

Perhaps call this project: "Spring Cleaning"?

[hadley]

The tidyverse convention for package documentation is:

#' @keywords internal
"_PACKAGE"

It's not perfect, but it builds a basic doc using information from DESCRIPTION (the idea being to avoid duplicating the same information in multiple places). It occurs to me that this could also look for a _pkgdown.yml and if present use that to build an index of all the functions in the package.

[gaborcsardi]

@hadley it would be also great to somehow include the README as well. Or generate the package docs from the README. Or the other way, with a new roclet.

[hadley]

@gaborcsardi I agree in principle, but in practice I couldn't come up with a reasonable way to share text across two such different formats. Maybe we could parse the README and then you'd select which sections you want in the package docs based on the heading name? (i.e. so you could drop the installation section).

I also think having an index of package functions is probably more useful than recapitulating the readme.

[gaborcsardi]

I agree in principle, but in practice I couldn't come up with a reasonable way to share text across two such different formats

We would just take part of the README (details to be worked out), and parse it with roxygen's Markdown parser.

Actually, sometimes even installation instructions don't hurt. It is not always the case that the user installed the package on the system.

I also think having an index of package functions is probably more useful than recapitulating the readme.

Sure. That is useful as well.

[jennybc]

One of the things I've needed to apologize for

Here's another thing you can add to the list: inconsistency about how to access the package-level man page. Try ?dplyr, package?dplyr, ?purrr, ?stringr to see what I mean. I don't immediately see what's causing this difference, but didn't want to forget to log this little hang nail. I guess package?dplyr has always been the proper way to access, but I have enjoyed it when ?dplyr just works.

[hadley]

@gaborcsardi maybe it could just use the same principle as pkgdown, basically taking everything after the badges. I think we'd also need a few tweaks to make sure images ended up in the right place (i.e. man/figures) but that should be straightforward. We'd also need to think through what happens if you use some unsupported markdown.

@jennybc I think that should mostly be standardised now through my use of the snippet above. (?purrr and ?stringr work for me with the package versions I have installed)

[gaborcsardi]

@hadley

We'd also need to think through what happens if you use some unsupported markdown

AFAIK, GH uses the same markdown parser as roxygen/commonmark, we just need to turn on extensions in roxygen.

[karthik]

@jennybc

BTW why is it so hard to visit a package's index? I'm also happy to be told some trick I'm missing.

Slightly related: I also just have this function in my internal package/rprofile.

function (package, pattern, all.names = FALSE) 
{
  package <- deparse(substitute(package))
  ls(pos = paste("package", package, sep = ":"), all.names = all.names, 
    pattern = pattern)
}

Allowing me to list functions (essentially performing the function of the index):

lsp(ggplot2)

or search for patterns:

> lsp(ggplot2, "geom")
 [1] "geom_abline"          "geom_area"           
 [3] "geom_bar"             "geom_bin2d"          
...

[sfirke]

@karthik something similar to your function is pacman::p_funs(ggplot2)

[AmeliaMN]

@hrbrmstr I think almost every PR I've ever sent to Hadley's repos has been to make ?pkgname work. This indicates it is probably a good beginner task.

Like @jennybc, I'm almost always trying to get to the index of the package (have I ever remembered a single function from stringr? Seems unlikely). I'd be more than happy to have a function that just brings me there.

Somewhat related, @hadley and @jjallaire have certainly heard this feature request for RStudio, but I wish that when I ? a function that has been masked I would automatically be brought to the man page of the first function in the search path, with a sort of wikipedia-style disambiguation at the top ("there are three other functions in your loaded packages with the same name, see them [here]()"), but this is one of those pie-in-the-sky wishes that is probably outside the scope of the unconf.

[jsta]

Thanks for the tip @sfirke! Should save me a trip on my usual route that visits either the CRAN reference manual or the GH NAMESPACE file.