From b51e0ed356bc42544523dab8dbce7dadb52372ff Mon Sep 17 00:00:00 2001
From: memsharded <james@conan.io>
Date: Tue, 19 Jan 2021 13:32:18 +0100
Subject: [PATCH] docs for cmakedeps

---
 reference/conanfile/tools/cmake.rst | 97 ++++++++++++++++++++++++++++-
 1 file changed, 95 insertions(+), 2 deletions(-)

diff --git a/reference/conanfile/tools/cmake.rst b/reference/conanfile/tools/cmake.rst
index 8bea23d4406..b443cdaa6af 100644
--- a/reference/conanfile/tools/cmake.rst
+++ b/reference/conanfile/tools/cmake.rst
@@ -7,7 +7,43 @@ conan.tools.cmake
 
 CMakeDeps
 ---------
-Not yet available
+
+The ``CMakeDeps`` helper will generate one **xxxx-config.cmake** file per dependency, together with other necessary .cmake files
+like version, or configuration. It can be used like:
+
+
+.. code-block:: python
+
+    from conans import ConanFile
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+        generators = "CMakeDeps"
+
+
+The full instantiation, that allows custom configuration can be done in the ``generate()`` method:
+
+
+.. code-block:: python
+
+    from conans import ConanFile
+    from conan.tools.cmake import CMakeDeps
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+
+        def generate(self):
+            cmake = CMakeDeps(self)
+            cmake.configurations.append("ReleaseShared")
+            if self.options["hello"].shared:
+                cmake.configuration = "ReleaseShared"
+            cmake.generate()
+
+As it can be seen, it allows to define custom user CMake configurations besides the standard Release, Debug, etc ones.
+If the **settings.yml** file is customized to add new configurations to the ``settings.build_type``, then, adding it
+explicitly to ``.configurations`` is not necessary.
 
 
 CMakeToolchain
@@ -16,8 +52,65 @@ The ``CMakeToolchain`` is the toolchain generator for CMake. It will generate to
 command line invocation of CMake with the ``-DCMAKE_TOOLCHAIN_FILE=conantoolchain.cmake``. This generator translates
 the current package configuration, settings, and options, into CMake toolchain syntax.
 
+It can be declared as:
+
+.. code-block:: python
+
+    from conans import ConanFile
+
+    class Pkg(ConanFile):
+        generators = "CMakeToolchain"
+
+Or fully instantiated in the ``generate()`` method:
+
+.. code-block:: python
+
+    from conans import ConanFile
+    from conan.tools.cmake import CMakeToolchain
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+        generators = "cmake_find_package_multi"
+        options = {"shared": [True, False], "fPIC": [True, False]}
+        default_options = {"shared": False, "fPIC": True}
+
+        def generate(self):
+            tc = CMakeToolchain(self)
+            tc.variables["MYVAR"] = "MYVAR_VALUE"
+            tc.preprocessor_definitions["MYDEFINE"] = "MYDEF_VALUE"
+            tc.generate()
+
+
+This will generate a *conan_toolchain.cmake* file with the information provided in the ``generate()`` method as well as information
+translated from the current ``settings``.
+
 
 CMake
 -----
 The ``CMake`` build helper is a wrapper around the command line invocation of cmake. It will abstract the
-calls like ``cmake --build . --config Release`` into Python method calls.
+calls like ``cmake --build . --config Release`` into Python method calls. It will also add the argument
+``-DCMAKE_TOOLCHAIN_FILE=conantoolchain.cmake`` to the ``configure()`` call.
+
+
+.. code-block:: python
+
+    from conans import ConanFile
+    from conan.tools.cmake import CMake, CMakeToolchain, CMakeDeps
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+        options = {"shared": [True, False], "fPIC": [True, False]}
+        default_options = {"shared": False, "fPIC": True}
+
+        def generate(self):
+            tc = CMakeToolchain(self)
+            tc.generate()
+            deps = CMakeDeps(self)
+            deps.generate()
+
+        def build(self):
+            cmake = CMake(self)
+            cmake.configure()
+            cmake.build()
\ No newline at end of file