Generate API docs with Doxygen

The motivation is as stated in issue #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 #7814

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

flake.nix

@@ -98,7 +98,11 @@
           ];
 
         testConfigureFlags = [
-          "CXXFLAGS=-I${lib.getDev rapidcheck}/extras/gtest/include"
+          "RAPIDCHECK_HEADERS=${lib.getDev rapidcheck}/extras/gtest/include"
+        ];
+
+        internalApiDocsConfigureFlags = [
+          "--enable-internal-api-docs"
         ];
 
         nativeBuildDeps =
@@ -136,6 +140,10 @@
           rapidcheck
         ];
 
+        internalApiDocsDeps = [
+          buildPackages.doxygen
+        ];
+
         awsDeps = lib.optional (stdenv.isLinux || stdenv.isDarwin)
           (aws-sdk-cpp.override {
             apis = ["s3" "transfer"];
@@ -517,9 +525,7 @@
 
             src = self;
 
-            configureFlags = [
-              "CXXFLAGS=-I${lib.getDev pkgs.rapidcheck}/extras/gtest/include"
-            ];
+            configureFlags = testConfigureFlags;
 
             enableParallelBuilding = true;
 
@@ -536,6 +542,33 @@
             hardeningDisable = ["fortify"];
           };
 
+        # API docs for Nix's unstable internal C++ interfaces.
+        internal-api-docs =
+          with nixpkgsFor.x86_64-linux.native;
+          with commonDeps { inherit pkgs; };
+
+          stdenv.mkDerivation {
+            pname = "nix-internal-api-docs";
+            inherit version;
+
+            src = self;
+
+            configureFlags = testConfigureFlags ++ internalApiDocsConfigureFlags;
+
+            nativeBuildInputs = nativeBuildDeps;
+            buildInputs = buildDeps ++ propagatedDeps
+              ++ awsDeps ++ checkDeps ++ internalApiDocsDeps;
+
+            dontBuild = true;
+
+            installTargets = [ "internal-api-html" ];
+
+            postInstall = ''
+              mkdir -p $out/nix-support
+              echo "doc internal-api-docs $out/share/doc/nix/internal-api" >> $out/nix-support/hydra-build-products
+            '';
+          };
+
         # System tests.
         tests.authorization = runNixOSTestFor "x86_64-linux" ./tests/nixos/authorization.nix;
 
@@ -653,9 +686,11 @@
             nativeBuildInputs = nativeBuildDeps
                                 ++ (lib.optionals stdenv.cc.isClang [ pkgs.bear pkgs.clang-tools ]);
 
-            buildInputs = buildDeps ++ propagatedDeps ++ awsDeps ++ checkDeps;
+            buildInputs = buildDeps ++ propagatedDeps
+              ++ awsDeps ++ checkDeps ++ internalApiDocsDeps;
 
-            configureFlags = configureFlags ++ testConfigureFlags;
+            configureFlags = configureFlags
+              ++ testConfigureFlags ++ internalApiDocsConfigureFlags;
 
             enableParallelBuilding = true;