New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Contents starts_with returns all pages if no matches #728

Closed
md0u80c9 opened this Issue Jun 7, 2018 · 2 comments

Comments

Projects
None yet
2 participants
@md0u80c9
Copy link

md0u80c9 commented Jun 7, 2018

Hi,

I've used prefixes on some of my package files to identify internal or unsafe (in development) functions. I've just transplanted my work from my first package into my second.

In my _pkgdown.yml I've put the following code chunk:

reference:
  - title: In progress / unsafe functions
    desc:  >
      Functions in this category are recognised as being important.
      However they haven't been fully tested, or their API or
      precise role within the code hasn't been determined so should
      not be part of the fixed code. They start with the name
      "unsafe" until they are more complete and/or tested.
    contents:
    - starts_with("unsafe_")

Interestingly I don't currently have any documented functions which begin with unsafe_.

Rather than returning no sections (expected behaviour given no matches), this appears to return all sections (including of course the ones we've already indexed).

It looks like a bug rather than intended behaviour.

Not sure whether expected behaviour would be to report an error in the code, or to put a 'there are no functions in this section' line into the output, or both (you can see in my example of an unreleased package in development documenting the functions that we know we'll need but are scrappy pre-conceptual things is quite useful, and knowing there are none of them in the index is valuable).

Demonstrated on pkgdown 1.1.0 - but checking the changelog I can't see anything relating to this in the dev branch.

@jayhesselberth jayhesselberth added the bug label Jun 7, 2018

@md0u80c9

This comment has been minimized.

Copy link
Author

md0u80c9 commented Jun 9, 2018

Just done some testing today. I think it's wider than contents starts_with. I think (not yet proven conclusively) it is that if any section returns no entries, then it adds all entries.

@jayhesselberth

This comment has been minimized.

Copy link
Collaborator

jayhesselberth commented Jun 9, 2018

pkgdown behavior is confusing when when non-existing functions are selected.

A simple test package with:

a single function:

#' Test function
#' @export
test_func <- function() {}

and this config:

reference:
  - title: test
    contents:
    - starts_with("nothing")

returns a default_reference_index of:

- title: All functions
  desc: ~
  contents: '`test_func`'

when really it should warn that there are topics missing from the index.

In addition, this example should probably warn that starts_with("nothing") didn't return anything, as users would assume that each listing returns a function. I.e., what should happen if the typo starts_with("tset_") was the only listing in the example above?

@jayhesselberth jayhesselberth added the wip label Jun 9, 2018

jayhesselberth added a commit that referenced this issue Jun 10, 2018

Handle unmatched reference topics
Two scenarios are addressed:

* If a topic selector does not match anything, a warning is generated.

* If a _pkgdown.yml file has selectors but *none* of them match, a warning is generated saying all topics will be selected.

Closes #728

@jayhesselberth jayhesselberth added reference 📚 and removed bug labels Jun 10, 2018

jayhesselberth added a commit that referenced this issue Jun 26, 2018

Handle unmatched reference topics (#730)
Two scenarios are addressed:

* If a topic selector does not match anything, a warning is generated.

* If a _pkgdown.yml file has selectors but *none* of them match, a warning is generated saying all topics will be selected.

Closes #728
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment