CMake find modules update.

CMake/FindBreathe.cmake

@@ -1,31 +1,62 @@
 # FindBreathe.cmake
-# Copyright (C) 2021-2023 Manuel Sainz de Baranda y Goñi.
-# This "find module" is DISTRIBUTED AS PUBLIC DOMAIN. No restrictions apply.
+# Copyright (C) 2021-2024 Manuel Sainz de Baranda y Goñi.
+# This "find module" is distributed as public domain software.
+
+#[=======================================================================[.rst:
+FindBreathe
+-----------
+
+Find Breathe.
+
+Result variables
+^^^^^^^^^^^^^^^^
+
+This module will set the following variables in your project:
+
+``Breathe_FOUND``
+  ``TRUE`` if Breathe was found.
+
+``Breathe_APIDOC_VERSION``
+  The version of the ``breathe-apidoc`` executable that was found.
+
+``Breathe_VERSION``
+  Same as ``Breathe_APIDOC_VERSION``.
+
+Cache variables
+^^^^^^^^^^^^^^^
+
+Search results are saved persistently in CMake cache entries:
+
+``Breathe_APIDOC_EXECUTABLE``
+  The full path to the ``breathe-apidoc`` executable.
+
+#]=======================================================================]
 
 include(FindPackageHandleStandardArgs)
 
 find_program(
-	BREATHE_APIDOC_EXECUTABLE
+	Breathe_APIDOC_EXECUTABLE
 	NAMES breathe-apidoc
-	DOC "Breathe extension for Sphinx")
+	DOC "`breathe-apidoc` executable.")
 
-if(BREATHE_APIDOC_EXECUTABLE)
+if(Breathe_APIDOC_EXECUTABLE)
 	execute_process(
-		COMMAND "${BREATHE_APIDOC_EXECUTABLE}" --version
-		OUTPUT_VARIABLE _output)
+		COMMAND "${Breathe_APIDOC_EXECUTABLE}" --version
+		OUTPUT_VARIABLE _Breathe_output)
 
-	if("${_output}" MATCHES ".* ([^\n]+)\n")
-		set(BREATHE_APIDOC_VERSION "${CMAKE_MATCH_1}")
+	if("${_Breathe_output}" MATCHES ".* ([0-9]+(\\.[0-9]+(\\.[0-9]+)?)?).*\n")
+		set(Breathe_APIDOC_VERSION "${CMAKE_MATCH_1}")
+		set(Breathe_VERSION ${Breathe_APIDOC_VERSION})
 	endif()
 
-	unset(_output)
+	unset(_Breathe_output)
 endif()
 
 find_package_handle_standard_args(
 	Breathe
-	REQUIRED_VARS BREATHE_APIDOC_EXECUTABLE
-	VERSION_VAR BREATHE_APIDOC_VERSION)
+	REQUIRED_VARS Breathe_APIDOC_EXECUTABLE
+	VERSION_VAR Breathe_VERSION)
 
-mark_as_advanced(BREATHE_APIDOC_EXECUTABLE)
+mark_as_advanced(Breathe_APIDOC_EXECUTABLE)
 
 # FindBreathe.cmake EOF

CMake/FindSphinx.cmake

@@ -1,31 +1,115 @@
 # FindSphinx.cmake
-# Copyright (C) 2021-2023 Manuel Sainz de Baranda y Goñi.
-# This "find module" is DISTRIBUTED AS PUBLIC DOMAIN. No restrictions apply.
+# Copyright (C) 2021-2024 Manuel Sainz de Baranda y Goñi.
+# This "find module" is distributed as public domain software.
 
-include(FindPackageHandleStandardArgs)
+#[=======================================================================[.rst:
+FindSphinx
+----------
+
+Find the Sphinx documentation tools.
+
+Optional components
+^^^^^^^^^^^^^^^^^^^
+
+This module supports 4 optional ``COMPONENTS``:
+
+``apidoc``
+  Looks for the ``sphinx-apidoc`` executable.
+
+``autogen``
+  Looks for the ``sphinx-autogen`` executable.
+
+``build``
+  Looks for the ``sphinx-build`` executable. This component is used by default
+  if no components are specified.
+
+``quickstart``
+  Looks for the ``sphinx-quickstart`` executable.
+
+Result variables
+^^^^^^^^^^^^^^^^
+
+This module will set the following variables in your project:
+
+``Sphinx_FOUND``
+  ``TRUE`` if all requested Sphinx tools were found.
+
+``Sphinx_<TOOL>_VERSION``
+  The version of the ``sphinx-<component>`` executable that was found, where
+  ``<COMPONENT>`` and ``<component>`` are the uppercase and lowercase names of
+  the component, respectively.
+
+``Sphinx_VERSION``
+  The version of Sphinx that was found. It is the same as
+  ``Sphinx_BUILD_VERSION`` if the ``build`` component was requested; otherwise,
+  it is the same as the first one requested.
+
+Cache variables
+^^^^^^^^^^^^^^^
 
-find_program(
-	SPHINX_BUILD_EXECUTABLE
-	NAMES sphinx-build
-	DOC "Sphinx Documentation Builder")
+Search results are saved persistently in CMake cache entries:
 
-if(SPHINX_BUILD_EXECUTABLE)
-	execute_process(
-		COMMAND "${SPHINX_BUILD_EXECUTABLE}" --version
-		OUTPUT_VARIABLE _output)
+``Sphinx_<COMPONENT>_EXECUTABLE``
+  The full path to the ``sphinx-<component>`` executable, where ``<COMPONENT>``
+  and ``<component>`` are the uppercase and lowercase names of the component,
+  respectively.
 
-	if("${_output}" MATCHES ".* ([^\n]+)\n")
-		set(SPHINX_BUILD_VERSION "${CMAKE_MATCH_1}")
+#]=======================================================================]
+
+set(_Sphinx_required_vars)
+
+if(NOT Sphinx_FIND_COMPONENTS)
+	set(Sphinx_FIND_COMPONENTS build)
+endif()
+
+foreach(_Sphinx_tool IN LISTS Sphinx_FIND_COMPONENTS)
+	if(NOT _Sphinx_tool MATCHES "^(apidoc|autogen|build|quickstart)$")
+		message(FATAL_ERROR "Invalid components: ${Sphinx_FIND_COMPONENTS}")
+	endif()
+
+	string(TOUPPER ${_Sphinx_tool} _Sphinx_tool_uppercase)
+	set(_Sphinx_tool_executable_var Sphinx_${_Sphinx_tool_uppercase}_EXECUTABLE)
+
+	if(NOT DEFINED ${_Sphinx_tool_executable_var})
+		find_program(
+			${_Sphinx_tool_executable_var}
+			NAMES sphinx-${_Sphinx_tool}
+			DOC "`sphinx-${_Sphinx_tool}` executable.")
+
+		if(${_Sphinx_tool_executable_var})
+			execute_process(
+				COMMAND "${${_Sphinx_tool_executable_var}}" --version
+				OUTPUT_VARIABLE _Sphinx_output)
+
+			if("${_Sphinx_output}" MATCHES ".* ([0-9]+(\\.[0-9]+(\\.[0-9]+)?)?).*\n")
+				list(APPEND _Sphinx_required_vars ${_Sphinx_tool_executable_var})
+				mark_as_advanced(${_Sphinx_tool_executable_var})
+				set(Sphinx_${_Sphinx_tool_uppercase}_VERSION "${CMAKE_MATCH_1}")
+
+				if(NOT DEFINED Sphinx_VERSION)
+					set(Sphinx_VERSION ${Sphinx_${_Sphinx_tool_uppercase}_VERSION})
+				endif()
+			endif()
+
+			unset(_Sphinx_output)
+		endif()
 	endif()
 
-	unset(_output)
+	unset(_Sphinx_tool_executable_var)
+	unset(_Sphinx_tool_uppercase)
+endforeach()
+
+if(DEFINED Sphinx_BUILD_VERSION)
+	set(Sphinx_VERSION ${Sphinx_BUILD_VERSION})
 endif()
 
+include(FindPackageHandleStandardArgs)
+
 find_package_handle_standard_args(
 	Sphinx
-	REQUIRED_VARS SPHINX_BUILD_EXECUTABLE
-	VERSION_VAR SPHINX_BUILD_VERSION)
+	REQUIRED_VARS ${_Sphinx_required_vars}
+	VERSION_VAR Sphinx_VERSION)
 
-mark_as_advanced(SPHINX_BUILD_EXECUTABLE)
+unset(_Sphinx_required_vars)
 
 # FindSphinx.cmake EOF