New hook: parsable-roxygen

[owenjonesuob]

trafficstars

Is your feature request related to a problem? Please describe.

R developers often writes documentation in the form of "roxygen comments", in the same file as their code. If the syntax of that commentary is wrong, roxygen2::roxygenise() will throw an error. It can be frustrating when automated builds fail for this reason.

In my particular case, I have a GitHub Action which calls roxygenise() on a set of R files, and then uses the output files for a static documentation site - i.e. in theory there is no need to run roxygenise() to generate output files locally.

Describe the solution you'd like

We could create a relatively simple hook, à la parsable-R, to check that R scripts can be parsed successfully with roxygen2::parse_file().

Describe alternatives you've considered

One can run roxygenise() locally to check that it won't error, and then delete any generated output files from the local machine.

Additional context

I don't think this would be too tricky to add - the logic is almost identical to parsable-R, except using roxygen2::parse_file() instead of base::parse(). There is an extra dependency of {roxygen2} of course.

I can open a PR containing my prototype of parsable-roxygen, which currently lives in a private repo :innocent:

[lorenzwalthert]

Good idea. So are you not source tracking man/? Was not aware of this functionality in {roxygen2}. I guess it would be implemented with language: script as the language: r would be an overkill in this situation and running the hook on CI would not be required anyways.

[owenjonesuob]

My case is actually a bit unusual... I'm not working with a package, but rather, a repo containing {box} modules (there are more details in this blog post, if you're interested!). So my process looks something like:

1. Write roxygen comments within R scripts (box modules)
2. Commit files to repo and push
3. When changes are pushed/merged to main branch, a GitHub Actions workflow is triggered which:
   1. Runs roxygenise() with a custom roclet, which translates the roxygen comments into markdown files
   2. Builds a static HTML documentation site with mkdocs
   3. Publishes that site using GitHub Pages

This has two advantages:

• The docsite always stays aligned with the source (the developer can't forget to rebuild the docs!)
• The intermediate md/output HTML files don't have to live in the repo (well, the output HTML ends up living in a special gh-pages branch - but only because I am then hosting the docsite with GitHub Pages!)

I wonder if anyone else is doing anything this convoluted to build their docs... :sweat_smile: