18

Because each and every file in the man/ directory of an R package is automatically written with package roxygen2, I wonder what would prevent me from adding the entire directory to my .gitignore.

In other words, why all R packages on GitHub still version the man/ directory?

F. Privé
  • 11,423
  • 2
  • 27
  • 78
  • 9
    Because you can't compile a package without `/man`. Yes, you can roxygenize the docs, but that's another step. Hopefully this will one day become modus operandi for building R packages. `roxygen2` will have to come a long way, though. – Roman Luštrik Aug 23 '17 at 09:11
  • @RomanLuštrik You mean that `devtools::install_github` won't work? – F. Privé Aug 23 '17 at 09:27
  • 1
    Of course any wrapper can be made around `R CMD build`, but that's not the point. :) Technically you are correct, you can omit `/man` and count on the user to run `roxygenize` prior to compiling and installing the package. – Roman Luštrik Aug 23 '17 at 09:37
  • 1
    I'd suggest removing the `git` tag since this is not a question related to git, but solely to R. You'd have the same problem in any other VCS, so it's not `git` specific at all. – gucce Nov 21 '17 at 15:22
  • @gucce I talk about GitHub and .gitignore in my question. – F. Privé Nov 21 '17 at 15:44
  • 1
    I can see that. But with that argument in mind you'd also have to add a `GitHub` tag. I found this question because I can help people with Git. However, I don't see how any knowledge about Git (or GitHub for that matter) could help you with this specific question. – gucce Nov 22 '17 at 16:08

2 Answers2

4

As a convenience to users who use devtools::install_github().

If man/*.Rd is not in the repo, they will get a note like No man pages found in package... upon install and later, help(...) or ?... or ??... will fail for your users with No documentation or No results found.

Katrin Leinweber
  • 1,316
  • 13
  • 33
  • Are you sure of this? Can you see any example? – F. Privé Jul 06 '18 at 20:01
  • I experienced one recently when installing an R package of mine freshly on both Debian and macOS. If you want to test: `devtools::install_github("TIBHannover/BacDiveR", ref = "9252b807e08cc2e825f152d79c64d095c052da93"); library("BacDiveR"); ?retrieve_data` => as described above. – Katrin Leinweber Jul 14 '18 at 15:07
  • But if you try the [next `ref` (`b336e61c`)](https://github.com/TIBHannover/BacDiveR/commits/master?before=b336e61c31a71c8aac7e86dda274117edb8552d2+35), the help page appears. – Katrin Leinweber Jul 14 '18 at 15:14
1

If you want the man directory to be present but not the files generated in it, place a .gitignore file in the man directory. This will force git to generate the directory, but still ignore the files generated.

Ben
  • 298
  • 1
  • 8