Support for detecting R package documentation

[kelly-sovacool]

Existing issue check

• I found no existing issues covering this topic.

Description

almanack check currently requires documentation to be in the docs/ directory. However, R packages most commonly have long-form docs in the vignettes/ directory, and tools like pkgdown are used to build a complete website with content from the vignettes, docstrings in the source code, and other files like the README and NEWS (R's variant of a changelog).

Example

Here's an example of a popular R package which does not have a docs directory, but does have complete and detailed documentation.

https://github.com/tidyverse/ggplot2
https://ggplot2.tidyverse.org/

Would you like to work on a solution for this?

• Yes I am willing to submit a PR!

[d33bs]

Thanks @kelly-sovacool, love that we could expand this work to help support R projects. I'm on board with what you proposed!

I wonder if we should distinguish documentation checks based on the predominant language used for the project? For instance, if the project uses primarily Python we might not expect that same kind of documentation tree as an R project. We can distinguish this information via remote_repo_data.get("language", None) or the metric repo-primary-language. What do you think, open to how you might approach it.

I saw you were interested in making a contribution here. Please don't hesitate to open a PR when ready. If you have any questions along the way please let us know.

[kelly-sovacool]

Great, I'm happy to work on implementing this!

I wonder if we should distinguish documentation checks based on the predominant language used for the project?

I think using the repo's primary language would work for the majority of cases, but it wouldn't work for situations where a project is an R package but the primary language is C++ or Rust (e.g. https://github.com/RcppCore/Rcpp). All R packages must have a DESCRIPTION file in the root directory, so detecting that should be a fool-proof way to detect R packages specifically. Alternatively, we could forego trying to detect the package language altogether and instead just allow the presence of either docs/ or vignettes/ to satisfy this check.

Do you anticipate other situations where a check should behave differently depending on the repo's language?