Include "All other functions" in a pkgdown reference yaml

Question

I have a pkgdown site in which I group a number of functions into categories in the reference .yml file. I'm wondering if there is a way to put all of the functions which I didn't explicitly categorize into their own category. The only thought I had was to use the matches function like so:

reference:
- title: "someCategory"
  contents:
  - myFunction
- title: "other"
  contents:
  - matches(".*")

But this puts myFunction in both the "someCategory" and "other" categories. What I'd like to do is match all functions which aren't in a category.

Thanks!

score 6 · Answer 1 · answered Sep 02 '17 at 11:23

In pkgdown, there is already a feature to warn you about the topics that are missing in your yaml file. You can see the code by typing pkgdown:::data_reference_index.

So, basically, if you just modify this code a little, you can return the names of the functions that are missing from the index.

library(purrr)
data_reference_index_missing <- function(pkg = ".", depth = 1L) {
  pkg <- pkgdown:::as_pkgdown(pkg)

  meta <- pkg$meta[["reference"]] %||% default_reference_index(pkg)
  if (length(meta) == 0) {
    return(list())
  }

  # Cross-reference complete list of topics vs. topics found in index page
  all_topics <- meta %>%
    map(~ pkgdown:::select_topics(.$contents, pkg$topics)) %>%
    reduce(union)
  in_index <- seq_along(pkg$topics$name) %in% all_topics

  missing <- !in_index & !pkg$topics$internal
  pkg$topics$name[missing]
}

This was helpful. I ran `mymiss<-data_reference_index_missing(); paste(mymmiss, collapse = "- ")` and then copy-pasted the output of that into the .yml, adding returns. I like the programmatic approach below but couldn't make work. — Michael Roswell, Dec 09 '21 at 23:13

lbusett · Accepted Answer · 2017-09-02T10:32:06.650

If you don't mind running a function to update your yaml, running this from the root of your package should work (use "overwrite = FALSE" for testing: it will create a _pkgdown_new.yaml file.):

update_yaml <- function(mypkg, overwrite = FALSE) {
  require(yaml)
  #   _____________________________________________________________________
  #   Find currently missing functions in yaml file                    ####
  curr_yaml     <- yaml.load_file("_pkgdown.yaml")
  curr_yaml_ref <- curr_yaml[["reference"]]
  curr_funcs <- unlist(lapply(curr_yaml_ref,
                              FUN = function(x) (x$contents))) %>%
    gsub('`', "", .)
  all_pkgfuncs <- ls(paste0("package:", mypkg))
  miss_funcs   <- setdiff(pkg_funcs, curr_funcs)

  if (length(miss_funcs) == 0) {
    message("All functions are already in _pkgdown.yaml")
  } else {

    #   _________________________________________________________________
    #   Look if an "Other" section already exists                     ####

    titles     <- unlist(lapply(curr_yaml_ref, FUN = function(x) (x$title)))
    other_sect <- which(titles == "Other")

    if (!length(other_sect) == 0) {
      #   _________________________________________________________________
      #   If the "Other" sect already exists, append missing functions ####

      message(strwrap(paste(
        "Adding ", paste0("`", miss_funcs, "` ", collapse = ""),
        "to _pkgdown.yaml")))
      curr_yaml_ref[[other_sect]] = list(
        title = "Other",
        desc  = "Other Functions",
        contents = c(curr_yaml_ref[[other_sect]]$contents,
                     paste0("`", miss_funcs, "`"))
      )

    } else {

      #   _____________________________________________________________
      #   Otherwise, create the "other" section and add            ####

      message("Creating the \"Others\" section")
      message(strwrap(paste(
        "Adding ", paste0("`", miss_funcs, "` ", collapse = ""),
        "to _pkgdown.yaml")))
      curr_yaml_ref[[length(curr_yaml_ref) + 1]] = list(
        title = "Other",
        desc  = "Other Functions",
        contents = paste0("`", miss_funcs, "`"))
    }
    curr_yaml[["reference"]] <- curr_yaml_ref
    if (overwrite) {
      write(as.yaml(curr_yaml), "_pkgdown.yaml")
    } else {
      write(as.yaml(curr_yaml), "_pkgdown_new.yaml")
    }
  }
}

> update_yaml("sprawl", overwrite = F)

Creating the "Others" section
Adding er_crop_object er_getbands er_points er_polygons reproj_rast setClasses``setinfo_rast sprawl_scalebar to _pkgdown.yaml

The function browses the current .yaml file and finds the currently missing functions. If any are found, they are added to the "Others" section of the .yaml (which is automatically created if not already present).

I did a quick test and it seems to work properly.

HTH !

This looks like ti should be super useful, but I played for a sec and didn't get it working. First issue was ".yaml" vs. ".yml". A combination of @F. Privet's approach and this one would be really nice to have somehwere! — Michael Roswell, Dec 09 '21 at 23:16

C8H10N4O2 · Answer 3 · 2017-08-29T03:31:27.597

0

I'm not familiar with pkgdown, but for a limited case like this it might be feasible to use matches with regex for does not equal any of these

Regex negations are not efficient, and you will have to retype the names of your categorized functions, so again this might work in your limited case but is not a best practice.

Would something like this work? (test here)

- title: "other"
  contents:
  - matches('^(?!.*(myFunction|myOtherFunction|yetAnotherFunction)).*$')

edited Aug 29 '17 at 03:31

answered Aug 29 '17 at 03:15

C8H10N4O2

18,312
8
98
134

For a somewhat tricker and less efficient use case, see [regex for string not **containing** multiple specific words](https://stackoverflow.com/questions/7801581/regex-for-string-not-containing-multiple-specific-words) – C8H10N4O2 Aug 29 '17 at 03:33
That's a good idea, but I don't think it's feasible for lots of functions (say you had a hundred functions in the package. Also mostly what I'm trying to catch is when someone adds a new function but forgets to update the `yml` – Shorpy Aug 29 '17 at 16:27

Include "All other functions" in a pkgdown reference yaml

3 Answers3