Basic docs for integrations (#2988)

* start

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* remove conan 1.x mention

* minor changes

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

integrations.rst

@@ -3,3 +3,28 @@
 
 Integrations
 ============
+
+Conan provides seamless integration with several platforms, build systems, and IDEs. Conan
+brings off-the-shelf support for some of the most important operating systems, including
+Windows, Linux, macOS, Android, and iOS. Some of the most important build systems
+supported by Conan include CMake, MSBuild, Meson and Autotools. In addition to build
+systems, Conan also provides integration with popular IDEs, such as Visual Studio and
+Xcode.
+
+.. toctree::
+   :maxdepth: 2
+
+   integrations/cmake
+   integrations/visual_studio
+   integrations/autotools
+   integrations/xcode
+   integrations/meson
+   integrations/android
+
+.. warning::
+
+    Even though there's a plugin for Visual Studio IDE and another for CLion, it's not
+    recommended to use them right now because they're not updated for the 2.0 version yet.
+    However, we intend to resume working on these plugins and enhance their functionality
+    once Conan 2.0 is released.
+

integrations/android.rst

@@ -0,0 +1,14 @@
+.. _integrations_android:
+
+|android_logo| Android
+==========================
+
+Conan provides support for cross-building for Android, and it's easy to integrate with
+Android Studio. Please check these examples for more information on how to build your
+binaries for Android: 
+
+- :ref:`Cross building to Android with the NDK<examples_cross_build_android_ndk>`
+
+- :ref:`Integrating Conan in Android Studio<examples_cross_build_android_studio>`
+
+.. |android_logo| image:: ../images/integrations/conan-android-logo.png

integrations/autotools.rst

@@ -0,0 +1,32 @@
+.. _integrations_autotools:
+
+|autotools_logo| Autotools
+==========================
+
+Conan provides different tools to help manage your projects using Autotools. They can be
+imported from ``conan.tools.gnu``. The most relevant tools are:
+
+- `AutotoolsDeps`: the dependencies generator for Autotools, which generates shell scripts
+  containing environment variable definitions that the Autotools build system can
+  understand.
+
+- `AutotoolsToolchain`: the toolchain generator for Autotools, which generates shell
+  scripts containing environment variable definitions that the Autotools build system can
+  understand.
+
+- `Autotools` build helper, a wrapper around the command line invocation of autotools that
+  abstracts calls like `./configure` or `make` into Python method calls.
+
+- `PkgConfigDeps`: the dependencies generator for `pkg-config` which generates
+  `pkg-config` files for all the required dependencies of a package.
+
+For the full list of tools under ``conan.tools.gnu`` please check the :ref:`reference
+<conan_tools_gnu>` section. 
+
+.. seealso::
+
+    - Reference for :ref:`AutotoolsDeps<conan_tools_gnu_autotoolsdeps>`,
+      :ref:`AutotoolsToolchain<conan_tools_gnu_autotoolstoolchain>`, :ref:`Autotools<conan_tools_gnu_build_helper>` and
+      :ref:`PkgConfigDeps<conan_tools_gnu_pkgconfigdeps>`.
+
+.. |autotools_logo| image:: ../images/integrations/conan-autotools-logo.png

integrations/cmake.rst

@@ -0,0 +1,38 @@
+.. _integrations_cmake:
+
+|cmake_logo| CMake
+==================
+
+Conan provides different tools to integrate with CMake in a transparent way. Using these
+tools, the consuming ``CMakeLists.txt`` file does not need to be aware of Conan at all. The
+CMake tools also provide better IDE integration via cmake-presets.
+
+To learn how to integrate Conan with your current CMake project you can follow the
+:ref:`Conan tutorial <tutorial>` that uses CMake along all the sections.
+
+Please also check the reference for the CMakeDeps, CMakeToolchain, and CMake tools:
+
+- `CMakeDeps`: responsible for generating the CMake config files for all the required
+  dependencies of a package.
+
+- `CMakeToolchain`: generates all the information needed for CMake to build the packages
+  according to the information passed to Conan about things like the operating system, the
+  compiler to use, architecture, etc. It will also generate `cmake-presets` files for easy
+  integration with some IDEs that support this CMake feature off-the-shelf.
+
+- `CMake` build helper is the tool used by Conan to run CMake and will pass all the
+  arguments that CMake needs to build successfully, such as the toolchain file, build type
+  file, and all the CMake definitions set in the recipe.
+
+
+.. seealso::
+
+    - Check the :ref:`Building your project using CMakePresets
+      <examples-tools-cmake-toolchain-build-project-presets>` example
+    - Reference for :ref:`CMakeDeps <conan_tools_cmakedeps>`, :ref:`CMakeToolchain
+      <conan_tools_cmaketoolchain>` and :ref:`CMake build helper
+      <conan_tools_cmake_helper>`
+    - :ref:`Conan tutorial <tutorial>`
+
+
+.. |cmake_logo| image:: ../images/integrations/conan-cmake-logo.png

integrations/meson.rst

@@ -0,0 +1,25 @@
+.. _integrations_meson:
+
+|meson_logo| Meson
+==================
+
+Conan provides different tools to help manage your projects using Meson. They can be
+imported from ``conan.tools.meson``. The most relevant tools are:
+
+- `MesonToolchain`: generates the .ini files for Meson with the definitions of all the
+  Meson properties related to the Conan options and settings for the current package,
+  platform, etc. MesonToolchain normally works together with
+  :ref:`PkgConfigDeps<conan_tools_gnu_pkgconfigdeps>` to manage all the dependencies.
+
+- `Meson` build helper, a wrapper around the command line invocation of Meson.
+
+.. seealso::
+
+    - Reference for :ref:`MesonToolchain<conan_tools_meson_mesontoolchain>` and
+      :ref:`Meson<conan_tools_meson_meson>`.
+    - Build a simple Meson project using Conan
+      :ref:`example<examples_tools_meson_toolchain_build_simple_meson_project>`
+
+Build a simple Meson project using Conan
+
+.. |meson_logo| image:: ../images/integrations/conan-meson-logo.svg

integrations/visual_studio.rst

@@ -0,0 +1,36 @@
+.. _integrations_visual_studio:
+
+|visual_studio_logo| Visual Studio
+==================================
+
+Conan provides several tools to help manage your projects using Microsoft Visual Studio.
+These tools can be imported from ``conan.tools.microsoft`` and allow for native
+integration with Microsoft Visual Studio, without the need to use CMake and instead
+directly using Visual Studio solutions, projects, and property files. The most relevant
+tools are:
+
+- `MSBuildDeps`: the dependency information generator for Microsoft MSBuild build system.
+  It will generate multiple ``xxxx.props`` properties files, one per dependency of a
+  package, to be used by consumers using MSBuild or Visual Studio, just by adding the
+  generated properties files to the solution and projects.
+
+- `MSBuildToolchain`: the toolchain generator for MSBuild. It will generate MSBuild
+  properties files that can be added to the Visual Studio solution projects. This
+  generator translates the current package configuration, settings, and options, into
+  MSBuild properties files syntax.
+
+- `MSBuild` build helper is a wrapper around the command line invocation of MSBuild. It
+  will abstract the calls like ``msbuild "MyProject.sln" /p:Configuration=<conf>
+  /p:Platform=<platform>`` into Python method calls.
+
+For the full list of tools under ``conan.tools.microsoft`` please check the
+:ref:`reference <conan_tools_microsoft>` section.
+
+
+.. seealso::
+
+    - Reference for :ref:`MSBuildDeps<conan_tools_microsoft_msbuilddeps>`,
+      :ref:`MSBuildToolchain<conan_tools_microsoft_msbuildtoolchain>` and
+      :ref:`MSBuild<conan_tools_microsoft_msbuild>`.
+
+.. |visual_studio_logo| image:: ../images/integrations/conan-visual_studio-logo.png

integrations/xcode.rst

@@ -0,0 +1,35 @@
+.. _integrations_xcode:
+
+|xcode_logo| Xcode
+==================
+
+Conan provides different tools to integrate with Xcode IDE, providing all the necessary
+information about the dependencies, build options and also to build projects created with
+Xcode in recipes. They can be imported from ``conan.tools.apple``. The most relevant tools are:
+
+Please also check the reference for the CMakeDeps, CMakeToolchain, and CMake tools:
+
+- `XcodeDeps`: the dependency information generator for Xcode. It will generate multiple
+  `.xcconfig` configuration files, that can be used by consumers using xcodebuild in the
+  command line or adding them to the Xcode IDE.
+
+- `XcodeToolchain`: the toolchain generator for Xcode. It will generate .xcconfig
+  configuration files that can be added to Xcode projects. This generator translates the
+  current package configuration, settings, and options, into Xcode .xcconfig files syntax.
+
+- `XcodeBuild` build helper is a wrapper around the command line invocation of Xcode. It
+  will abstract the calls like ``xcodebuild -project app.xcodeproj -configuration <config>
+  -arch <arch> ...``
+
+
+For the full list of tools under ``conan.tools.apple`` please check the :ref:`reference
+<conan_tools_apple>` section. 
+
+.. seealso::
+
+    - Reference for :ref:`XcodeDeps<conan_tools_apple_xcodedeps>`, :ref:`XcodeToolchain
+      <conan_tools_apple_xcodetoolchain>` and :ref:`XcodeBuild build helper
+      <conan_tools_apple_xcodebuild>`
+
+
+.. |xcode_logo| image:: ../images/integrations/conan-xcode-logo.jpg

reference/conanfile_txt.rst

@@ -57,7 +57,7 @@ In practice the ``[tool_requires]`` will be always installed (same as ``[require
 something is going to be built, so the tool requirements are indeed needed.
 Note however, that by default ``tool_requires`` live in the "build" context, they cannot be libraries to built with, just executable
 tools, and for example, using the ``CMakeDeps`` generator, they will not create CMake config files for them (an exception is possible,
-but it requires using a ``conanfile.py``, read the :ref:`CMakeDeps reference<CMakeDeps>` for more information).
+but it requires using a ``conanfile.py``, read the :ref:`CMakeDeps reference<conan_tools_cmakedeps>` for more information).
 
 
 [test_requires]

reference/tools/cmake/cmake.rst

@@ -1,4 +1,4 @@
-.. _conan-cmake-build-helper:
+.. _conan_tools_cmake_helper:
 
 CMake
 =====

reference/tools/cmake/cmake_layout.rst

@@ -86,7 +86,7 @@ The values assigned by the ``cmake_layout`` (installing the Release/shared confi
 
 So we can keep separated folders for any number of different configurations that we want to install.
 
-The ``CMakePresets.json`` file generated at the :ref:`CMakeToolchain<conan-cmake-toolchain>`
+The ``CMakePresets.json`` file generated at the :ref:`CMakeToolchain<conan_tools_cmaketoolchain>`
 generator, will also take this ``tools.cmake.cmake_layout:build_folder_vars`` config into account to generate different
 names for the presets, being very handy to install N configurations and building our project for any of them by
 selecting the chosen preset.

reference/tools/cmake/cmakedeps.rst

@@ -1,4 +1,4 @@
-.. _CMakeDeps:
+.. _conan_tools_cmakedeps:
 
 CMakeDeps
 =========

reference/tools/cmake/cmaketoolchain.rst

@@ -1,4 +1,5 @@
 .. _conan-cmake-toolchain:
+.. _conan_tools_cmaketoolchain:
 
 CMakeToolchain
 ==============
@@ -137,7 +138,7 @@ cache_variables
 
 This attribute allows defining CMake cache-variables. These variables, unlike the ``variables``, are single-config. They
 will be stored in the ``CMakePresets.json`` file (at the `cacheVariables` in the `configurePreset`) and will be
-applied with ``-D`` arguments when calling ``cmake.configure`` using the :ref:`CMake() build helper<conan-cmake-build-helper>`.
+applied with ``-D`` arguments when calling ``cmake.configure`` using the :ref:`CMake() build helper<conan_tools_cmake>`.
 
 
 .. code:: python