Generate API docs with Doxygen

The motivation is as stated in issue NixOS#7814: even though the the C++ API
is internal and unstable, people still want it to be well documented for
sake of learning, code review, and other purposes that aren't predicated
on it being stable.

Fixes NixOS#7814

Makefile

@@ -32,6 +32,14 @@ makefiles += \
   mk/disable-tests.mk
 endif
 
+ifeq ($(api_docs), yes)
+makefiles += \
+  doc/api/local.mk
+else
+makefiles += \
+  mk/disable-api-docs.mk
+endif
+
 OPTIMIZE = 1
 
 ifeq ($(OPTIMIZE), 1)

Makefile.config.in

@@ -22,6 +22,7 @@ LOWDOWN_LIBS = @LOWDOWN_LIBS@
 OPENSSL_LIBS = @OPENSSL_LIBS@
 PACKAGE_NAME = @PACKAGE_NAME@
 PACKAGE_VERSION = @PACKAGE_VERSION@
+RAPIDCHECK_HEADERS = @RAPIDCHECK_HEADERS@
 SHELL = @bash@
 SODIUM_LIBS = @SODIUM_LIBS@
 SQLITE3_LIBS = @SQLITE3_LIBS@
@@ -46,3 +47,4 @@ storedir = @storedir@
 sysconfdir = @sysconfdir@
 system = @system@
 tests = @tests@
+api_docs = @api_docs@

configure.ac

@@ -152,6 +152,11 @@ AC_ARG_ENABLE(tests, AS_HELP_STRING([--disable-tests],[Do not build the tests]),
   tests=$enableval, tests=yes)
 AC_SUBST(tests)
 
+# Building without API docs is the default as the C++ API is not stable.
+AC_ARG_ENABLE(api_docs, AS_HELP_STRING([--enable-api-docs],[Build API docs for Nix unstable library interfaces]),
+  api_docs=$enableval, api_docs=no)
+AC_SUBST(api_docs)
+
 # LTO is currently broken with clang for unknown reasons; ld segfaults in the llvm plugin
 AC_ARG_ENABLE(lto, AS_HELP_STRING([--enable-lto],[Enable LTO (only supported with GCC) [default=no]]),
   lto=$enableval, lto=no)
@@ -286,6 +291,8 @@ PKG_CHECK_MODULES([GTEST], [gtest_main])
 # Look for rapidcheck.
 # No pkg-config yet, https://github.com/emil-e/rapidcheck/issues/302
 AC_LANG_PUSH(C++)
+AC_SUBST(RAPIDCHECK_HEADERS)
+[CXXFLAGS="-I $RAPIDCHECK_HEADERS $CXXFLAGS"]
 AC_CHECK_HEADERS([rapidcheck/gtest.h], [], [], [#include <gtest/gtest.h>])
 dnl No good for C++ libs with mangled symbols
 dnl AC_CHECK_LIB([rapidcheck], [])

doc/api/.gitignore

@@ -0,0 +1,3 @@
+/doxygen.cfg
+/html
+/latex