Build Doxygen web site

Make use of the nice documenting comments I've added over the
years to build some developer documentation.

The generated pages are not installed (but could be if there is
demand).

Signed-off-by: Chuck Lever <[email protected]>

Author: chucklever

.gitignore

@@ -5,6 +5,7 @@ configure.ac~
 configure
 configure~
 cscope.*
+docs/doxygen/
 Makefile
 Makefile.in
 .deps/

Makefile.am

@@ -20,5 +20,6 @@ AUTOMAKE_OPTIONS	= foreign
 
 EXTRA_DIST		= autogen.sh CONTRIBUTING.md LICENSE.txt \
 			  README.md SECURITY.md
-SUBDIRS			= etc man src systemd
+SUBDIRS			= docs etc man src systemd
+
 MAINTAINERCLEANFILES	= Makefile.in cscope.* ktls-utils*.tar.gz

configure.ac

@@ -64,6 +64,12 @@ PKG_CHECK_MODULES([LIBNL_GENL3], libnl-genl-3.0 >= 3.1)
 AC_SUBST([LIBNL_GENL3_CFLAGS])
 AC_SUBST([LIBNL_GENL3_LIBS])
 
+AC_CHECK_PROG(DOXYGEN, doxygen, doxygen, false)
+if test "$DOXYGEN" = false; then
+   AC_MSG_WARN([Doxygen not found - documentation will not be built])
+fi
+AM_CONDITIONAL([HAVE_DOXYGEN], [test "$DOXYGEN" != "false"])
+
 AC_CHECK_LIB([gnutls], [gnutls_handshake_set_secret_function],
              [AC_DEFINE([HAVE_GNUTLS_QUIC], [1],
 			[Define to 1 if you have the gnutls_handshake_set_secret_function function.])])
@@ -94,6 +100,8 @@ fi
 AC_SUBST([AM_CPPFLAGS])
 
 AC_CONFIG_FILES([Makefile \
+                 docs/Doxyfile \
+                 docs/Makefile \
                  etc/Makefile \
                  etc/tlshd/Makefile \
                  man/Makefile \

docs/Doxyfile.in

@@ -0,0 +1,29 @@
+#
+# Copyright (c) 2025 Oracle and/or its affiliates.
+#
+# ktls-utils is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as
+# published by the Free Software Foundation; version 2.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301, USA.
+#
+
+EXTRA_DIST		= Doxyfile.in
+
+if HAVE_DOXYGEN
+doxygen: Doxyfile
+	$(DOXYGEN) Doxyfile
+endif
+
+clean-local:
+	-rm -rf doxygen/ latex/ man/
+
+MAINTAINERCLEANFILES	= Makefile.in

docs/Makefile.am

@@ -16,5 +16,7 @@
 # 02110-1301, USA.
 #
 
+EXTRA_DIST		= mainpage.c
+
 SUBDIRS			= tlshd
 MAINTAINERCLEANFILES	= Makefile.in

src/Makefile.am

@@ -0,0 +1,20 @@
+/**
+ * @cond skip
+ * vim:syntax=doxygen
+ * @endcond
+
+@mainpage
+
+@section main_intro Introduction
+
+In-kernel TLS consumers need a mechanism to perform TLS handshakes
+on a connected socket to negotiate TLS session parameters that can
+then be programmed into the kernel's TLS record protocol engine.
+
+This package of software provides a TLS handshake user agent that
+listens for kernel requests and then materializes a user space
+socket endpoint on which to perform these handshakes. The resulting
+negotiated session parameters are passed back to the kernel via
+standard kTLS socket options.
+
+ */

src/mainpage.c

@@ -48,6 +48,18 @@
 
 #include "tlshd.h"
 
+/**
+ * @page config Configuration
+ *
+ * @section man5 Man pages
+ * @subsection tlshd_conf_5 tlshd.conf.5
+ * @htmlinclude tlshd.conf.5.html
+ *
+ * @section examples Configuration examples
+ * @subsection tlshd_conf /etc/tlshd/config
+ * @verbinclude config
+ */
+
 /**
  * @var GKeyFile *tlshd_configuration
  * In-memory parsed config file

src/tlshd/config.c

@@ -51,6 +51,22 @@
 
 #include "tlshd.h"
 
+/**
+ * @page tlshd TLS handshake daemon
+ *
+ * The tlshd daemon is a user agent that services TLS handshake
+ * requests on behalf of kernel TLS consumers. It materializes kernel
+ * socket endpoints in user space in order to perform TLS handshakes
+ * using a standard TLS library. After each handshake completes, tlshd
+ * plants the TLS session key into the socket to enable the use of
+ * kTLS to secure subsequent communication on that socket. The socket
+ * is then passed back to the kernel.
+ *
+ * @section man8 Man pages
+ * @subsection tlshd_8 tlshd.8
+ * @htmlinclude tlshd.8.html
+ */
+
 static const char *optstring = "c:hsv";
 static const struct option longopts[] = {
 	{ "config",	required_argument,	NULL,	'c' },