Feature request to integrate Doxygen documentation into pkgdown setup

[Henrik Sloot]

Summary

R packages sometimes contain separate pure-C++ code (e.g., a wrapper API to an external library). If this includes an API that can be linked to from other packages via LinkingTo:, it might be desirable to include Doxygen-like documentation in C++ code and to also include this in a pkgdown-generated website.

Currently, this is very difficult to do. An approach that I found is using Doxygen + Breathe + Sphinx + RTD with the following file structure (excluding all configuration details for readability):

./
|- pkgdown/
|  |- _pkgdown.yml
|  |- cpp/
|  |   |- conf.py
|  |   |- Doxyfile
|  |   |- index.rst
|  |- assets/sphinx/

and the build script

# sudo apt-get update && sudo apt-get update
# sudo apt-get install -y doxygen graphviz python3-sphinx libgsl-dev
# pip install --upgrade pip
# pip install sphinx_rtd_theme
# pip install breathe
(cd pkgdown/cpp && (\
  doxygen Doxyfile \
  sphinx-build -b HTML ../assets/sphinx \
  touch ../assets/sphinx/.nojekyll))
Rscript -e 'pkgdown::build_site()' 

This allows to deploy a nice RTD-themed documentation of C++ code with pkgdown to GH-pages. However, there are multiple issues:

• Configuration is rather complicated (I am not even sure if that approach sketched above is that sound).
• Requires manual back-and-forth linking between the pkgdown site and the RTD site.
• The C++ documentation has its own theme and is not "integrated" into the pkgdown site.

Proposal

I am aware this is non-standard and might not be suitable to integrate something like this in pkgdown itself (esp. with the additional dependencies). However, I still think an integration might be useful. If you consider pursuing this, I have three approaches in mind:

1. A vignette or example package giving instructions about how to include C++ documentation in a pkgdown-generated site.
2. A companion package that extends pkgdown to simplify/standardize this.
3. Maybe the simplest approach would be a combination of a vignette and allowing to specify a pre-build script in _pkgdown.yml.

Additional context

• An approach only using pkgdown+Doxygen can be found here: https://bertcarnell.github.io/lhs/index.html
• An approach using pkgdown+Doxygen+Breathe+Sphinx+RTD can be found here: https://hsloot.github.io/integratecpp/
• Background (using cmake is optional): https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
• Other packages that include

[dmurdoch]

I'm not familiar with the issues documenting C++, but the same sort of issue can arise in a package that exports a lot of Javascript for html widgets, e.g. rgl. I use JSDoc manually to produce the pages (and I notice that I forgot to run it on the current version of the web page,
https://dmurdoch.github.io/rgl/). So a solution here should be flexible; I think your suggestion 3 would do it.

[Hadley Wickham]

I think unfortunately this is out of scope for pkgdown. It's a nice idea but it'll be a large amount of effort and we already have bigger tasks (like supporting multiple versions) that are higher up my priority list.