Add docs for check_max_cppstd and valid_max_cppstd (#2643)

* Document the check/valid max cppstd tooling

* Update tutorial/creating_packages/preparing_the_build.rst

Co-authored-by: James <james@conan.io>

reference/tools/build.rst

@@ -45,6 +45,16 @@ conan.tools.build.check_min_cppstd()
 .. autofunction:: check_min_cppstd
 
 
+.. _conan_tools_build_check_max_cppstd:
+
+conan.tools.build.check_max_cppstd()
+""""""""""""""""""""""""""""""""""""
+
+.. currentmodule:: conan.tools.build.cppstd
+
+.. autofunction:: check_max_cppstd
+
+
 conan.tools.build.valid_min_cppstd()
 """"""""""""""""""""""""""""""""""""
 
@@ -53,6 +63,14 @@ conan.tools.build.valid_min_cppstd()
 .. autofunction:: valid_min_cppstd
 
 
+conan.tools.build.valid_max_cppstd()
+""""""""""""""""""""""""""""""""""""
+
+.. currentmodule:: conan.tools.build.cppstd
+
+.. autofunction:: valid_max_cppstd
+
+
 conan.tools.build.default_cppstd()
 """"""""""""""""""""""""""""""""""
 

tutorial/creating_packages/add_dependencies_to_packages.rst

@@ -31,9 +31,9 @@ You will notice some changes in the `conanfile.py` file from the previous recipe
 Let's check the relevant parts:
 
 .. code-block:: python
-    
+
     ...
-    from conan.tools.build import check_min_cppstd
+    from conan.tools.build import check_max_cppstd, check_min_cppstd
     ...
 
     class helloRecipe(ConanFile):
@@ -46,6 +46,7 @@ Let's check the relevant parts:
 
         def validate(self):
             check_min_cppstd(self, "11")
+            check_max_cppstd(self, "14")
 
         def requirements(self):
             self.requires("fmt/8.1.1")
@@ -76,8 +77,9 @@ Let's check the relevant parts:
   recipe. We already used this method in the :ref:`consuming packages
   section<consuming_packages_flexibility_of_conanfile_py>` to raise an error for
   non-supported configurations. Here, we call the
-  :ref:`check_min_cppstd()<conan_tools_build_check_min_cppstd>` to check that we are at
-  least using C++11 standard in our settings.
+  :ref:`check_min_cppstd()<conan_tools_build_check_min_cppstd>` and
+  :ref:`check_max_cppstd()<conan_tools_build_check_max_cppstd>` to check that we are using at
+  least C++11 and at most C++14 standards in our settings.
 
 
 You can check the new sources, using the fmt library in the

tutorial/creating_packages/preparing_the_build.rst

@@ -47,7 +47,7 @@ Let's check the relevant parts:
     :emphasize-lines: 12,16,20,27,30,35
 
     ...
-    from conan.tools.build import check_min_cppstd
+    from conan.tools.build import check_max_cppstd, check_min_cppstd
     ...
 
     class helloRecipe(ConanFile):
@@ -67,6 +67,7 @@ Let's check the relevant parts:
         def validate(self):
             if self.info.options.with_fmt:
                 check_min_cppstd(self, "11")
+                check_max_cppstd(self, "14")
 
         def source(self):
             git = Git(self)
@@ -95,7 +96,7 @@ As you can see:
 * Based on the value of the ``with_fmt`` option:
 
     - We install or not the ``fmt/8.1.1`` Conan package.
-    - We require or not a minimum C++ standard as the *fmt* library requires at least C++11.
+    - We require or not a minimum and a maximum C++ standard as the *fmt* library requires at least C++11 and it will not compile if we try to use a standard above C++14 (just an example, *fmt* can build with more modern standards)
     - We inject the ``WITH_FMT`` variable with the value ``True`` to the :ref:`CMakeToolchain<conan-cmake-toolchain>` so that we
       can use it in the *CMakeLists.txt* of the **hello** library to add the CMake **fmt::fmt** target
       conditionally.
@@ -201,4 +202,4 @@ Read more
 ---------
 
 - Use the ``generate()`` method to import files from dependencies.
-- More based on the examples mentioned above ... 
+- More based on the examples mentioned above ...