Skip to content
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.

Sign up for GitHub

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

Jump to bottom

New hook: parsable-roxygen #562

Open
owenjonesuob opened this issue May 4, 2024 · 2 comments · May be fixed by #563
Open

New hook: parsable-roxygen #562

owenjonesuob opened this issue May 4, 2024 · 2 comments · May be fixed by #563

Comments

@owenjonesuob
Copy link

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 😇
@lorenzwalthert
Copy link
Owner

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
Copy link
Author

owenjonesuob commented May 6, 2024 •
edited

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... 😅

@owenjonesuob owenjonesuob linked a pull request May 9, 2024 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add parsable-roxygen hook owenjonesuob/precommit
2 participants
@lorenzwalthert @owenjonesuob