Merge pull request #1992 from memsharded/feature/cmakedeps

docs for cmakedeps

reference/conanfile/tools/cmake.rst

@@ -10,7 +10,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
@@ -19,18 +55,74 @@ 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()
 
 
 conf
 ++++
 
 - ``tools.microsoft:msbuild_verbosity`` will accept one of ``"Quiet", "Minimal", "Normal", "Detailed", "Diagnostic"`` to be passed
   to the ``CMake.build()`` command, when a Visual Studio generator (MSBuild build system) is being used for CMake. It is passed as
-  an argument to the underlying build system via the call ``cmake --build . --config Release -- /verbosity:Diagnostic``
+  an argument to the underlying build system via the call ``cmake --build . --config Release -- /verbosity:Diagnostic``
+