diff --git a/default.nix b/default.nix
index bdfe93b1..a1782e91 100644
--- a/default.nix
+++ b/default.nix
@@ -138,7 +138,7 @@ let
             xo-subsys         = self.callPackage pkgs/xo-subsys.nix         {};
             xo-randomgen      = self.callPackage pkgs/xo-randomgen.nix      {                   buildExamples = true; };
             xo-reflectutil    = self.callPackage pkgs/xo-reflectutil.nix    {};
-            xo-arena          = self.callPackage pkgs/xo-arena.nix          {};
+            xo-arena          = self.callPackage pkgs/xo-arena.nix          { buildDocs = true; };
             xo-facet          = self.callPackage pkgs/xo-facet.nix          {};
             xo-refcnt         = self.callPackage pkgs/xo-refcnt.nix         {};
             xo-ordinaltree    = self.callPackage pkgs/xo-ordinaltree.nix    {};
diff --git a/pkgs/xo-arena.nix b/pkgs/xo-arena.nix
index b216ba6c..4b67f35d 100644
--- a/pkgs/xo-arena.nix
+++ b/pkgs/xo-arena.nix
@@ -1,12 +1,19 @@
 {
   # nixpkgs dependencies
-  stdenv, cmake, catch2,
+  lib, stdenv, cmake, catch2,
+  doxygen,
+
+  python3Packages,
+
+  sphinx, graphviz,
 
   # xo dependencies
-  xo-cmake,
   xo-randomgen,
   xo-reflectutil,
   xo-indentlog,
+  xo-cmake,
+
+  buildDocs ? false,
 } :
 
 stdenv.mkDerivation (finalattrs:
@@ -15,13 +22,29 @@ stdenv.mkDerivation (finalattrs:
 
     src = ../xo-arena;
 
-    cmakeFlags = ["-DCMAKE_MODULE_PATH=${xo-cmake}/share/cmake"
-                  "-DENABLE_TESTING=1"
-                 ];
+    cmakeFlags = ["-DCMAKE_MODULE_PATH=${xo-cmake}/share/cmake"]
+                  ++ lib.optionals buildDocs ["-DXO_ENABLE_DOCS=on"]
+                  ++ ["-DENABLE_TESTING=1"];
+
+    inherit buildDocs;
     doCheck = true;
+
+    postBuild = lib.optionalString buildDocs ''
+      cmake --build . -- docs
+    '';
+
     nativeBuildInputs = [
       cmake catch2
       xo-cmake xo-randomgen
+    ] ++ lib.optionals buildDocs [
+      doxygen
+      sphinx
+      graphviz
+      python3Packages.sphinx-rtd-theme
+      python3Packages.breathe
+      python3Packages.sphinxcontrib-ditaa
+      python3Packages.sphinxcontrib-plantuml
+      python3Packages.pillow
     ];
     propagatedBuildInputs = [
       xo-reflectutil
diff --git a/xo-arena/CMakeLists.txt b/xo-arena/CMakeLists.txt
index 36fbfcb0..0b6c7020 100644
--- a/xo-arena/CMakeLists.txt
+++ b/xo-arena/CMakeLists.txt
@@ -28,4 +28,9 @@ add_subdirectory(utest)
 
 xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
 
+# ----------------------------------------------------------------
+# docs targets depend on all the other library/utest targets
+#
+add_subdirectory(docs)
+
 # end CMakeLists.txt
diff --git a/xo-arena/docs/AllocInfo-reference.rst b/xo-arena/docs/AllocInfo-reference.rst
new file mode 100644
index 00000000..05da0eac
--- /dev/null
+++ b/xo-arena/docs/AllocInfo-reference.rst
@@ -0,0 +1,26 @@
+.. _AllocInfo-reference:
+
+AllocInfo Reference
+===================
+
+Describes a single allocation.
+Requires allocator configured to store per-allocation headers
+
+Context
+-------
+
+.. ditaa::
+    :--scale: 0.99
+
+    +-----------------------------------------------------+
+    |                       DArena                        |
+    |                   DArenaIterator                    |
+    +-----------------------------------------------------+
+    |                     ArenaConfig                     |
+    +--------------+------------------------+-------------+
+    |              |        AllocInfo   cBLU|             |
+    |              +------------------------+             |
+    | AllocError   |  AllocHeaderConfig     |  cmpresult  |
+    |              +------------------------+             |
+    |              |      AllocHeader       |             |
+    +--------------+------------------------+-------------+
diff --git a/xo-arena/docs/cmpresult-reference.rst b/xo-arena/docs/cmpresult-reference.rst
index 46998543..ecaa4ba2 100644
--- a/xo-arena/docs/cmpresult-reference.rst
+++ b/xo-arena/docs/cmpresult-reference.rst
@@ -37,7 +37,7 @@ Class
 Constructors
 ------------
 
-.. doxgyengroup:: mm-cmpresult-ctors
+.. doxygengroup:: mm-cmpresult-ctors
 
 Methods
 -------
diff --git a/xo-arena/include/xo/arena/cmpresult.hpp b/xo-arena/include/xo/arena/cmpresult.hpp
index 0a9a9110..bf09af57 100644
--- a/xo-arena/include/xo/arena/cmpresult.hpp
+++ b/xo-arena/include/xo/arena/cmpresult.hpp
@@ -24,7 +24,7 @@ namespace xo {
             return os;
         }
 
-        /** Result of a generic comparison operation
+        /** @brief result of a generic comparison operation
          **/
         struct cmpresult {
             /** @defgroup mm-cmpresult-ctors cmpresult ctors **/