mlysy
Generate from header in inst/include?
I have packages that export C++ header files located in inst/include. Can I use this package to document them?
I have the same question and I am also wondering if this package is planning on continuing to be maintained as the last release was quite some time ago. Thanks 🙏
First of all, delighted to hear that rdoxygen might be useful to you!
I have packages that export C++ header files located in inst/include. Can I use this package to document them?
tl;dr
Yes, as long as you aren't trying to create doxygen vignettes. In other words, you can run rdoxygen::doxy(vignettes = FALSE) and it will create the doxygen documentation for you -- minus the vignettes.
No doxygen vignettes?
The integration of doxygen documentation into the R vignette system is what stalled this project many years ago. Specifically, we originally tried to inject the doxygen html output into an R vignette via inst/doc (details here). However, devtools (which pretty much everyone uses for package development) deletes the inst/doc folder when you run e..g, devtools::build_vignettes(). After a long discussion about this with the devtools team, we came to the conclusion that even if we managed to inject doxygen html input into an R vignette, that would add considerable size to the package and CRAN would probably complain if you tried to host it there.
Some alternatives are:
- Host the doxygen html somewhere else. For example, I'm pretty sure you could do something like pkgdown + gh-pages, though I haven't tried it myself.
- Convert the doyxgen html output into an actual R vignette, i.e., it would literally look like an Rmd file with
output: html_vignette. We tried this a while ago with something like this: doxygen -> xml output -> moxygen -> Rmd vignette. Reasonably detailed notes on how far we got with this approach are available here, with sample code in the enclosing folder.
Ultimately we didn't pursue this last approach further because (i) we were hoping to avoid the moxygen dependency (though maybe it's not that big a deal after all) and (ii) the vignette output was a bit ugly / difficult to navigate and there wasn't much support to work on this aspect in our day jobs. However, if you're interested in picking up the doxygen vignette problem I would be more than happy to discuss a PR :)
Hmm even without vignettes you'll probably want to add inst/doxygen to .Rbuildignore before submitting to CRAN...
Thank you for all of the info, I will explore using {rdoxygen} as is and then potentially discuss future PR if we get that far. Thanks again 😃!