Merge Release/1.32.0 to master

creating_packages/toolchains.rst

@@ -3,8 +3,8 @@ Toolchains
 
 .. warning:
 
-    This is a very **EXPERIMENTAL** feature, introduced in Conan 1.26, only supporting CMake
-    and with limited functionality, and subject to breaking changes in the future.
+    This is a very **EXPERIMENTAL** feature, introduced in Conan 1.26, with limited functionality,
+    and subject to breaking changes in the future.
     The current goal is to gather experience and feedback
     to evolve it, while adding more build systems.
 
@@ -62,7 +62,6 @@ deduced from the current configuration of ``self.settings`` and ``self.options``
 
 .. code:: python
 
-    from conan.tools.cmake import CMakeToolchain
     from conans.tools import save
 
     def generate(self):
@@ -110,10 +109,14 @@ the documentation of each toolchain to check the associated build helper availab
 Built-in toolchains
 -------------------
 
+.. warning::
+
+    Toolchain reference is moving to :ref:`conan_tools`
+
 .. toctree::
    :maxdepth: 2
 
    toolchains/cmake
    toolchains/make
    toolchains/meson
-   toolchains/msbuild
+

reference/conanfile.rst

@@ -23,4 +23,5 @@ Contents:
 
    conanfile/attributes
    conanfile/methods
+   conanfile/tools
    conanfile/other

reference/conanfile/tools.rst

@@ -0,0 +1,40 @@
+.. _conan_tools:
+
+tools
+=====
+
+Tools are all things that can be imported and used in Conan recipes.
+
+.. warning::
+
+    These tools are **experimental** and subject to breaking changes.
+
+.. important::
+
+    This is the current design for Conan 2.0, and these will be the supported tools. Only the tools documented
+    in this section will be available in Conan 2.0.
+
+
+The import path is always like:
+
+.. code-block:: python
+
+    from conan.tools.cmake import CMakeToolchain, CMakeDeps, CMake
+    form conan.tools.microsoft import MSBuildToolchain, MSBuildDeps, MSBuild
+
+
+The main guidelines are:
+
+- Everything that recipes can import belong to ``from conan.tools``. Any other thing is private implementation
+  and shouldn't be used in recipes.
+- Only documented, public (not preceded by ``_``) tools can be used in recipes.
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   tools/cmake
+   tools/microsoft
+

reference/conanfile/tools/cmake.rst

@@ -0,0 +1,23 @@
+conan.tools.cmake
+=================
+
+.. warning::
+
+    These tools are **experimental** and subject to breaking changes.
+
+CMakeDeps
+---------
+Not yet available
+
+
+CMakeToolchain
+--------------
+The ``CMakeToolchain`` is the toolchain generator for CMake. It will generate toolchain files that can be used in the
+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.
+
+
+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.