diff --git a/default.nix b/default.nix
index 2b867d10..d0d0f48d 100644
--- a/default.nix
+++ b/default.nix
@@ -77,7 +77,6 @@ let
 
       in
         {
-          xo-tokenizer      = self.callPackage pkgs/xo-tokenizer.nix      { buildDocs = true; };
           xo-reader         = self.callPackage pkgs/xo-reader.nix         {};
 
           xo-jit            = self.callPackage pkgs/xo-jit.nix            { #stdenv = jitStdenv;
@@ -131,6 +130,7 @@ let
 
             xo-expression     = self.callPackage pkgs/xo-expression.nix     {                   buildExamples = true; };
             xo-pyexpression   = self.callPackage pkgs/xo-pyexpression.nix   {};
+            xo-tokenizer      = self.callPackage pkgs/xo-tokenizer.nix      { buildDocs = true; buildExamples = true; };
             xo-pyjit          = self.callPackage pkgs/xo-pyjit.nix          {};
             #
             xo-userenv        = self.callPackage pkgs/xo-userenv.nix        {};
diff --git a/pkgs/xo-tokenizer.nix b/pkgs/xo-tokenizer.nix
index 2a4e2c19..9d21d04b 100644
--- a/pkgs/xo-tokenizer.nix
+++ b/pkgs/xo-tokenizer.nix
@@ -1,8 +1,15 @@
 {
   # dependencies
-  stdenv, cmake, catch2,
+  lib, stdenv, cmake, catch2,
 
-  xo-cmake, xo-indentlog
+  python3Packages,
+
+  doxygen, sphinx, graphviz,
+
+  xo-cmake, xo-indentlog,
+
+  buildDocs ? false,
+  buildExamples ? false,
 } :
 
 stdenv.mkDerivation (finalattrs:
@@ -12,11 +19,32 @@ stdenv.mkDerivation (finalattrs:
 
     src = ../xo-tokenizer;
 
-    cmakeFlags = ["-DCMAKE_MODULE_PATH=${xo-cmake}/share/cmake" "-DXO_ENABLE_EXAMPLES"];
+    cmakeFlags = ["-DCMAKE_MODULE_PATH=${xo-cmake}/share/cmake"]
+                 ++ lib.optionals buildDocs ["-DXO_ENABLE_DOCS=on"]
+                 ++ lib.optionals buildExamples ["-DXO_ENABLE_EXAMPLES=on"];
+
+    inherit buildDocs;
+    inherit buildExamples;
+
     doCheck = true;
+
     propagatedBuildInputs = [ ];
+
+    postBuild = lib.optionalString buildDocs ''
+      cmake --build . -- docs
+    '';
+
     nativeBuildInputs = [ cmake catch2
                           xo-cmake
                           xo-indentlog
-                        ];
+                        ]
+    ++ lib.optionals buildDocs [
+      doxygen
+      sphinx
+      graphviz
+      python3Packages.sphinx-rtd-theme
+      python3Packages.breathe
+      python3Packages.sphinxcontrib-ditaa
+      python3Packages.sphinxcontrib-plantuml
+    ];
   })
diff --git a/xo-tokenizer/CMakeLists.txt b/xo-tokenizer/CMakeLists.txt
index 74d93c9e..95130c2b 100644
--- a/xo-tokenizer/CMakeLists.txt
+++ b/xo-tokenizer/CMakeLists.txt
@@ -23,6 +23,10 @@ add_subdirectory(example)
 add_subdirectory(utest)
 xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
 
+if (XO_ENABLE_EXAMPLES)
+    install(TARGETS xo_tokenizer_repl DESTINATION bin/xo/example/tokenizer)
+endif()
+
 # ----------------------------------------------------------------
 # docs targets depend on all the other library/utest targets
 #
diff --git a/xo-tokenizer/docs/CMakeLists.txt b/xo-tokenizer/docs/CMakeLists.txt
index 1763e146..30289162 100644
--- a/xo-tokenizer/docs/CMakeLists.txt
+++ b/xo-tokenizer/docs/CMakeLists.txt
@@ -5,5 +5,5 @@ xo_docdir_doxygen_config()
 xo_docdir_sphinx_config(
     index.rst install.rst examples.rst implementation.rst
     input-state-class.rst scan-result-class.rst schematika-tokens.rst span-class.rst
-    token-class-rst tokenizer-error-class.rst tokentype-enum.rst
+    token-class.rst tokenizer-error-class.rst tokentype-enum.rst
 )
diff --git a/xo-tokenizer/example/tokenrepl/CMakeLists.txt b/xo-tokenizer/example/tokenrepl/CMakeLists.txt
index 8bf77b32..60243b7e 100644
--- a/xo-tokenizer/example/tokenrepl/CMakeLists.txt
+++ b/xo-tokenizer/example/tokenrepl/CMakeLists.txt
@@ -5,7 +5,7 @@ set(SELF_SRCS tokenrepl.cpp)
 
 if (XO_ENABLE_EXAMPLES)
     xo_add_executable(${SELF_EXE} ${SELF_SRCS})
-    xo_dependency(${SELF_EXE} xo_tokenizer)
+    xo_self_dependency(${SELF_EXE} xo_tokenizer)
 endif()
 
 # end CMakeLists.txt