CMakeDeps and CMakeToolchain improvements (#2209)

reference/conanfile/tools/cmake/cmakedeps.rst

@@ -163,14 +163,20 @@ The following properties affect the CMakeDeps generator:
 
 - **cmake_file_name**: The config file generated for the current package will follow the ``<VALUE>-config.cmake`` pattern,
   so to find the package you write ``find_package(<VALUE>)``.
-- **cmake_target_name**: Name of the target to be consumed. When set on the root ``cpp_info``,
-  it changes the namespace of the target. When set to a component, it changes the name of the target
-  (see the example below).
+- **cmake_target_name**: Name of the target to be consumed.
+- **cmake_target_namespace**: Namespace of the target to be consumed. If not specified, it will use **cmake_target_name**. This is only read when set on the root ``cpp_info`` (see the example below).
+- **cmake_find_mode**: Defaulted to ``config``. Possible values are:
+
+  - ``config``: The CMakeDeps generator will create config scripts for the dependency.
+  - ``module``: Will create module config (FindXXX.cmake) scripts for the dependency.
+  - ``both``: Will generate both config and modules.
+  - ``none``: Won't generate any file. It can be used, for instance, to create a system wrapper package so the consumers find the config files in the CMake installation config path and not in the generated by Conan (because it has been skipped).
+
+- **cmake_module_file_name**: Same as **cmake_file_name** but when generating modules with ``cmake_find_mode=module/both``. If not specified it will default to **cmake_file_name**.
+- **cmake_module_target_name**: Same as **cmake_target_name**  but when generating modules with ``cmake_find_mode=module/both``.  If not specified it will default to **cmake_target_name**.
+- **cmake_module_target_namespace**: Same as **cmake_target_namespace**  but when generating modules with ``cmake_find_mode=module/both``. This is only read when set on the root ``cpp_info``. If not specified it will default to **cmake_target_namespace**.
 - **cmake_build_modules**: List of ``.cmake`` files (route relative to root package folder) that are automatically
   included when the consumer run the ``find_package()``.
-- **skip_deps_file**: It tells the ``CMakeDeps`` generator to skip the creation of files for the package declaring
-  this property. It can be used, for instance, to create a system wrapper package so the consumers find
-  the config files in the CMake installation config path and not in the generated by Conan (because it has been skipped).
 
 Example:
 
@@ -182,11 +188,16 @@ Example:
         self.cpp_info.set_property("cmake_file_name", "MyFileName")
         # Foo:: namespace for the targets (Foo::Foo if no components)
         self.cpp_info.set_property("cmake_target_name", "Foo")
+        # self.cpp_info.set_property("cmake_target_namespace", "Foo")  # This can be omitted as the value is the same
+
         # Foo::Var target name for the component "mycomponent"
         self.cpp_info.components["mycomponent"].set_property("cmake_target_name", "Var")
         # Automatically include the lib/mypkg.cmake file when calling find_package()
         self.cpp_info.components["mycomponent"].set_property("cmake_build_modules", [os.path.join("lib", "mypkg.cmake")])
 
         # Skip this package when generating the files for the whole dependency tree in the consumer
         # note: it will make useless the previous adjustements.
-        self.cpp_info.set_property("skip_deps_file", True)
+        # self.cpp_info.set_property("cmake_find_mode", "none")
+
+        # Generate both MyFileNameConfig.cmake and FindMyFileName.cmake
+        self.cpp_info.set_property("cmake_find_mode", "both")

reference/conanfile/tools/cmake/cmaketoolchain.rst

@@ -126,6 +126,35 @@ This will be translated to:
 - One ``set()`` definition, using a cmake generator expression in ``conan_toolchain.cmake`` file,
   using the different values for different configurations.
 
+The booleans assigned to a variable will be translated to ``ON`` and ``OFF`` symbols in CMake:
+
+.. code:: python
+
+    def generate(self):
+        tc = CMakeToolchain(self)
+        tc.variables["FOO"] = True
+        tc.variables["VAR"] = False
+        tc.generate()
+
+
+Will generate the sentences: ``set(FOO ON ...)`` and ``set(VAR OFF ...)``.
+
+
+find_builddirs
+++++++++++++++
+
+Defaulted to ``True``. If ``True`` Conan adds the ``cpp_info.builddirs`` from the requirements to the
+``CMAKE_PREFIX_PATH`` and ``CMAKE_MODULE_PATH`` variables. That would allow finding the config files or modules
+packaged in the dependencies and also including them from the consumer CMakeLists.txt.
+
+.. code:: python
+
+    def generate(self):
+        tc = CMakeToolchain(self)
+        tc.find_builddirs = False
+        tc.generate()
+
+
 Generators
 ++++++++++