nix-build: xo-arena: build docs + minor doc facepalms

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    {};

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

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

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       |             |
+    +--------------+------------------------+-------------+

xo-arena/docs/cmpresult-reference.rst

@@ -37,7 +37,7 @@ Class
 Constructors
 ------------
 
-.. doxgyengroup:: mm-cmpresult-ctors
+.. doxygengroup:: mm-cmpresult-ctors
 
 Methods
 -------

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 **/