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>

4 files changed, 87 insertions, 1 deletions

diff --git a/doc/internal-api/.gitignore b/doc/internal-api/.gitignore
new file mode 100644
index 000000000..dab28b6b0
--- /dev/null
+++ b/doc/internal-api/.gitignore
@@ -0,0 +1,3 @@
+/doxygen.cfg
+/html
+/latex
diff --git a/doc/internal-api/doxygen.cfg.in b/doc/internal-api/doxygen.cfg.in
new file mode 100644
index 000000000..8f526536d
--- /dev/null
+++ b/doc/internal-api/doxygen.cfg.in
@@ -0,0 +1,63 @@
+# Doxyfile 1.9.5
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
+# double-quotes, unless you are using Doxywizard) that should identify the
+# project for which the documentation is generated. This name is used in the
+# title of most generated pages and in a few other places.
+# The default value is: My Project.
+
+PROJECT_NAME           = "Nix"
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
+# could be handy for archiving the generated documentation or if some version
+# control system is used.
+
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+
+# Using the PROJECT_BRIEF tag one can provide an optional one line description
+# for a project that appears at the top of each page and should give viewer a
+# quick idea about the purpose of the project. Keep the description short.
+
+PROJECT_BRIEF          = "Nix, the purely functional package manager; unstable internal interfaces"
+
+# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
+# The default value is: YES.
+
+GENERATE_LATEX         = NO
+
+# The INPUT tag is used to specify the files and/or directories that contain
+# documented source files. You may enter file names like myfile.cpp or
+# directories like /usr/src/myproject. Separate the files or directories with
+# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
+# Note: If this tag is empty the current directory is searched.
+
+# FIXME Make this list more maintainable somehow. We could maybe generate this
+# in the Makefile, but we would need to change how `.in` files are preprocessed
+# so they can expand variables despite configure variables.
+
+INPUT                  = \
+  src/libcmd \
+  src/libexpr \
+  src/libexpr/flake \
+  src/libexpr/tests \
+  src/libexpr/tests/value \
+  src/libexpr/value \
+  src/libfetchers \
+  src/libmain \
+  src/libstore \
+  src/libstore/build \
+  src/libstore/builtins \
+  src/libstore/tests \
+  src/libutil \
+  src/libutil/tests \
+  src/nix \
+  src/nix-env \
+  src/nix-store
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by the
+# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of
+# RECURSIVE has no effect here.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
+
+INCLUDE_PATH           = @RAPIDCHECK_HEADERS@
diff --git a/doc/internal-api/local.mk b/doc/internal-api/local.mk
new file mode 100644
index 000000000..890f341b7
--- /dev/null
+++ b/doc/internal-api/local.mk
@@ -0,0 +1,19 @@
+.PHONY: internal-api-html
+
+ifeq ($(internal_api_docs), yes)
+
+$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg
+	mkdir -p $(docdir)/internal-api
+	{ cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/internal-api" ; } | doxygen -
+
+# Generate the HTML API docs for Nix's unstable internal interfaces.
+internal-api-html: $(docdir)/internal-api/html/index.html
+
+else
+
+# Make a nicer error message
+internal-api-html:
+	@echo "Internal API docs are disabled. Configure with '--enable-internal-api-docs', or avoid calling 'make internal-api-html'."
+	@exit 1
+
+endif
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index 055882251..531168e3f 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -88,7 +88,8 @@ $(d)/builtins.json: $(bindir)/nix
 	@mv $@.tmp $@
 
 # Generate the HTML manual.
-html: $(docdir)/manual/index.html
+.PHONY: manual-html
+manual-html: $(docdir)/manual/index.html
 install: $(docdir)/manual/index.html
 
 # Generate 'nix' manpages.