Add sconsdeps docs (#3371)

* basic docs

* minor changes

* add deprecation warnings

* minor changes

* Update reference/conanfile/tools/scons.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

---------

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

integrations/build_system/scons.rst

@@ -5,8 +5,8 @@ ____________________
 
 .. warning::
 
-    This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines<conan2_migration_guide>`
-    to find the feature that replaced this one.
+    This is a **deprecated** feature. Please check the new :ref:`SConsDeps<conan_tools_sconsdeps>`
+    tool that will be compatible with Conan 2.X.
 
 SCons can be used both to generate and consume Conan packages via the :ref:`scons_generator`
 generator. The package recipe ``build()`` method could be similar to:

reference/conanfile/tools.rst

@@ -57,3 +57,4 @@ Contents:
    tools/scm
    tools/build
    tools/android
+   tools/scons

reference/conanfile/tools/scons.rst

@@ -0,0 +1,72 @@
+.. _conan_tools_sconsdeps:
+
+conan.tools.scons
+=================
+
+.. important::
+
+   Some of the features used in this section are still **under development**. While they
+   are recommended and usable, and we will try not to break them in future releases, some
+   breaking changes might still occur.
+
+SConsDeps
+---------
+
+Available since: `1.61.0 <https://github.com/conan-io/conan/releases>`_
+
+The ``SConsDeps`` is the dependency generator for `SCons <https://scons.org/>`_. It will
+generate a `SConscript_conandeps` file containing the necessary information for SCons to
+build against the desired dependencies.
+
+The ``SConsDeps`` generator can be used by name in conanfiles:
+
+.. code-block:: python
+   :caption: conanfile.py
+
+   from conan import ConanFile
+ 
+   class Pkg(ConanFile):
+       generators = "SConsDeps"
+
+.. code-block:: text
+   :caption: conanfile.txt
+
+   [generators] 
+   SConsDeps
+
+It can also be fully instantiated in the conanfile ``generate()`` method:
+
+.. code:: python
+
+   from conan import ConanFile 
+   from conan.tools.scons import SConsDeps
+
+   class App(ConanFile):
+       settings = "os", "arch", "compiler", "build_type"
+
+       def generate(self):
+           tc = SConsDeps(self) 
+           tc.generate()
+
+After executing the ``conan install`` command, the ``SConsDeps`` generator will create the
+`SConscript_conandeps` file. This file will provide the following information for `SCons`:
+``CPPPATH``, ``LIBPATH``, ``BINPATH``, ``LIBS``, ``FRAMEWORKS``, ``FRAMEWORKPATH``,
+``CPPDEFINES``, ``CXXFLAGS``, ``CCFLAGS``, ``SHLINKFLAGS``, and ``LINKFLAGS``. This information
+is generated for the accumulated list of all dependencies and also for each one of the
+requirements. You can load it in your consumer `SConscript` like this:
+
+.. code-block:: python
+    :caption: consumer `SConscript`
+
+    ...
+    info = SConscript('./SConscript_conandeps')
+    # You can use conandeps to get the information
+    # for all the dependencies.
+    flags = info["conandeps"] 
+
+    # Or use the name of the requirement if
+    # you only want the information about that one.
+    flags = info["zlib"] 
+
+    env.MergeFlags(flags)
+    ...

reference/generators/scons.rst

@@ -5,8 +5,8 @@ scons
 
 .. warning::
 
-    This is a **deprecated** feature. Please refer to the :ref:`Migration Guidelines<conan2_migration_guide>`
-    to find the feature that replaced this one.
+    This is a **deprecated** feature. Please check the new :ref:`SConsDeps<conan_tools_sconsdeps>`
+    tool that will be compatible with Conan 2.X.
 
 Conan provides :ref:`integration with SCons <scons>` with this generator.