diff --git a/CMakeLists.txt b/CMakeLists.txt
index 49085743..6d22c32a 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -11,7 +11,6 @@ xo_cxx_toplevel_options2()
 
 # ----------------------------------------------------------------
 # cmake -DCMAKE_BUILD_TYPE=coverage
-#
 xo_toplevel_coverage_config2()
 
 # ----------------------------------------------------------------
@@ -26,7 +25,6 @@ add_definitions(${PROJECT_CXX_FLAGS})
 
 add_subdirectory(example)
 add_subdirectory(utest)
-add_subdirectory(docs)
 
 # ----------------------------------------------------------------
 # provide find_package() support for projects using this library
@@ -36,6 +34,11 @@ xo_add_headeronly_library(${SELF_LIB})
 xo_install_library4(${SELF_LIB} ${PROJECT_NAME}Targets)
 xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
 
+# ----------------------------------------------------------------
+# docs targets depend on all the other library/utest targets
+#
+add_subdirectory(docs)
+
 # ----------------------------------------------------------------
 # dependencies
 
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 81b0092f..936d662d 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -1,116 +1,5 @@
 # xo-flatstring/docs/CMakeLists.txt
 
-if (XO_SUBMODULE_BUILD)
-    # in submodule build, rely on toplevel docs/CMakeLists.txt file instead
-else()
-    # build docs starting from here only in standalone build.
-    # otherwise use top-level doxygen setup instead.
-
-    set(ALL_LIBRARY_TARGETS xo_flatstring)  # todo: automate this from xo-cmake macros
-    set(ALL_UTEST_TARGETS xo_flatstring_ex1 ) # todo: automate this from xo-cmake macros
-
-    # look for doxygen executable
-    find_program(DOXYGEN_EXECUTABLE NAMES doxygen REQUIRED)
-    message("-- DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}")
-
-    # look for sphinx-build executable
-    find_program(SPHINX_EXECUTABLE NAMES sphinx-build REQUIRED)
-    message("-- SPHINX_EXECUTABLE=${SPHINX_EXECUTABLE}")
-
-    execute_process(COMMAND ${XO_CMAKE_CONFIG_EXECUTABLE} --doxygen-template OUTPUT_VARIABLE DOXYGEN_CONFIG_TEMPLATE)
-    message(STATUS "DOXYGEN_CONFIG_TEMPLATE=${DOXYGEN_CONFIG_TEMPLATE}")
-
-    set(DOX_CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-
-    set(DOX_INPUT_DIR ${PROJECT_SOURCE_DIR})
-    set(DOX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/dox)
-
-    set(DOX_INDEX_FILE ${DOX_OUTPUT_DIR}/html/index.html)
-
-    # .hpp files reachable from xo-flatstring/include
-    #
-    # REMINDER: for reliability will need to re-run cmake when the set of .hpp files changes
-    #
-    file(GLOB_RECURSE DOX_HPP_FILES_GLOB ${PROJECT_SOURCE_DIR}/include *.hpp)
-
-    set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx/html)
-    set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
-    #
-    # sphinx .rst files reachable from cmake-examples/docs
-    #
-    # REMINDER: for reliability will need to re-run cmake when the set of .rst files changes
-    #
-    file(GLOB_RECURSE SPHINX_RST_FILES_GLOB ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
-
-    set(SPHINX_RST_FILES index.rst install.rst lessons.rst flatstring-reference.rst flatstring-class.rst)
-
-    # TODO:
-    # 1. move Doxyfile.in to xo-cmake project
-    # 2. replace this command section with xo-cmake macro
-    #
-    configure_file(
-        ${DOXYGEN_CONFIG_TEMPLATE} ${DOX_CONFIG_FILE}
-        FILE_PERMISSIONS OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE
-        @ONLY)
-
-    set(DOX_DEPS ${ALL_LIBRARY_TARGETS} ${ALL_UTEST_TARGETS} ${DOX_HPP_FILES_GLOB})
-
-    file(MAKE_DIRECTORY ${DOX_OUTPUT_DIR})
-    add_custom_command(
-        OUTPUT ${DOX_INDEX_FILE}
-        DEPENDS ${DOX_DEPS}
-        COMMAND "${DOXYGEN_EXECUTABLE}" ${DOX_CONFIG_FILE}
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        MAIN_DEPENDENCY ${DOX_CONFIG_FILE}
-        COMMENT "Generating docs (doxygen)")
-
-    # To build this target
-    #   $ cmake --build .build -j -- doxygen
-    # or
-    #   $ cd .build
-    #   $ make doxygen
-    #
-    add_custom_target(
-        doxygen
-        DEPENDS ${DOX_INDEX_FILE} ${DOX_DEPS}
-    )
-
-    # root of sphinx doc tree
-    set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
-    set(SPHINX_DEPS doxygen conf.py ${SPHINX_RST_FILES} ${SPHINX_RST_FILES_GLOB} ${DOX_DEPS})
-
-    add_custom_command(
-        OUTPUT ${SPHINX_INDEX_FILE}
-        DEPENDS ${SPHINX_DEPS}
-        COMMAND ${SPHINX_EXECUTABLE}
-        -b html -Dbreathe_projects.xodoxxml=${CMAKE_CURRENT_BINARY_DIR}/dox/xml
-        ${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        COMMENT "Generating docs (sphinx) -> [${SPHINX_OUTPUT_DIR}]")
-
-    # make sphinx --> generate sphinx documentation
-    #
-    add_custom_target(
-        sphinx
-        DEPENDS ${SPHINX_INDEX_FILE})
-
-    # - html docs generated in build/docs/sphinx
-    # - copy the doc tree to share/doc/xo_unit/html
-    #
-    #  DESTINATION: CMAKE_INSTALL_DOCDIR
-    #                => DATAROOTDIR/doc/PROJECT_NAME
-    #                => CMAKE_INSTALL_PREFIX/share/doc/xo_flatstring
-    #  OPTIONAL:    install directory tree if it exists,
-    #               but don't complain if it's missing
-    install(
-        DIRECTORY ${SPHINX_OUTPUT_DIR}
-        FILE_PERMISSIONS OWNER_READ GROUP_READ WORLD_READ
-        DESTINATION ${CMAKE_INSTALL_DOCDIR}
-        COMPONENT Documentation
-        OPTIONAL)
-
-    # make docs --> generate sphinx documentation
-    add_custom_target(
-        docs
-        DEPENDS sphinx)
-endif()
+xo_doxygen_collect_deps()
+xo_docdir_doxygen_config()
+xo_docdir_sphinx_config(index.rst install.rst lessons.rst flatstring-reference.rst flatstring-class.rst)
diff --git a/utest/CMakeLists.txt b/utest/CMakeLists.txt
index 1779b465..88dff3fc 100644
--- a/utest/CMakeLists.txt
+++ b/utest/CMakeLists.txt
@@ -5,11 +5,7 @@ set(SELF_SRCS
     flatstring_utest_main.cpp
     flatstring.test.cpp)
 
-add_executable(${SELF_EXE} ${SELF_SRCS})
-xo_include_options2(${SELF_EXE})
-
-add_test(NAME ${SELF_EXE} COMMAND ${SELF_EXE})
-#target_code_coverage(${SELF_EXE} AUTO ALL)
+xo_add_utest_executable(${SELF_EXE} ${SELF_SRCS})
 
 # ----------------------------------------------------------------
 # in coverage build,  target to build+install coverage report