docs: "Usage" documentation updated with CMake presets usage

docs/usage.rst

@@ -86,26 +86,42 @@ in *~/.conan/profiles* directory. An example profile can look as follows:
     arch=x86_64
     arch_build=x86_64
     compiler=gcc
-    compiler.version=10
+    compiler.version=12
     compiler.cppstd=20
     compiler.libcxx=libstdc++11
     build_type=Release
 
-    [options]
-    [build_requires]
-
-    [conf]
-    tools.cmake.cmaketoolchain:generator=Ninja
-
     [env]
-    CC=/usr/bin/gcc-10
+    CC=/usr/bin/gcc-12
-    CXX=/usr/bin/g++-10
+    CXX=/usr/bin/g++-12
 
 .. tip::
 
     Please note that **mp-units** library requires C++20 to be set either in a Conan profile or forced
     via Conan command line. If you do the former, you will not need to provide ``-s compiler.cppstd=20``
-    every time your run a Conan command line (as it is suggested below).
+    every time your run a Conan command line (as provided in the command line instructions below).
+
+Additionally, it is recommended to set Ninja as a CMake generator for Conan. To do so you should create
+a *~/.conan/global.conf* file that will set ``tools.cmake.cmaketoolchain:generator`` to one of Ninja
+generators. For example:
+
+.. code-block:: text
+
+    tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
+
+.. note::
+
+  *~/.conan/global.conf* file may also set ``tools.cmake.cmake_layout:build_folder_vars``` which
+  `makes working with several compilers or build configurations easier
+  <https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout>`_.
+  For example the below line will force Conan to generate separate CMake presets and folders for each compiler:
+
+  .. code-block:: text
+
+      tools.cmake.cmake_layout:build_folder_vars=["settings.compiler", "settings.compiler.version"]
+
+  In such a case you will need to use a configuration specific preset name in the Conan instructions provided below
+  rather then just ``default`` and ``release`` (i.e. ``gcc-11`` and ``gcc-11-release``)
 
 
 Build Options
@@ -207,6 +223,21 @@ UNITS_USE_LIBFMT
 Enables usage of `{fmt} <https://github.com/fmtlib/fmt>`_ library instead of the C++20 Standard Library feature.
 
 
+CMake with Presets Support
+--------------------------
+
+It is recommended to use at least CMake 3.23 to build this project as this version introduced a support
+for CMake Presets schema version 4 used now by Conan to generate presets files. All build instructions
+below assume that you have such a support. If not, your CMake invocations have to be replaced to something
+like:
+
+.. code-block:: shell
+
+    mkdir build && cd build
+    cmake .. -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=<path_to_generators_dir>/conan_toolchain.cmake
+    cmake --build . --config Release
+
+
 Installation and Reuse
 ----------------------
 
@@ -298,8 +329,8 @@ library release the following steps may be performed:
 
       mkdir my_project/build && cd my_project/build
       conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
-      cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
+      cmake .. -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake
-      cmake --build .
+      cmake --build . --config Release
 
 
 Conan + CMake (Live At Head)
@@ -333,6 +364,9 @@ differences:
       [requires]
       mp-units/0.8.0@mpusz/testing
 
+      [layout]
+      cmake_layout
+
       [generators]
       CMakeToolchain
       CMakeDeps
@@ -347,10 +381,9 @@ differences:
 
   .. code-block:: shell
 
-      mkdir my_project/build && cd my_project/build
+      conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=outdated -u
-      conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=outdated -u
+      cmake --preset default
-      cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
+      cmake --build --preset release
-      cmake --build .
 
 
 Install
@@ -362,43 +395,60 @@ to find it, it is enough to perform the following steps:
 
 .. code-block:: shell
 
-    mkdir units/build && cd units/build
+    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
-    conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -b=missing
+    mv CMakeUserPresets.json src
-    cmake ../src -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
+    cd src
-    cmake --install . --prefix <install_dir>
+    cmake --preset default -DCMAKE_INSTALL_PREFIX=<your_installation_path>
+    cmake --build --preset release --target install
 
 
-Contributing (or just building all the tests, examples, and documentation)
+Contributing (or just building all the tests and examples)
---------------------------------------------------------------------------
+----------------------------------------------------------
 
-In case you would like to build all the source code (with unit tests and examples) and documentation
+In case you would like to build all the source code (with unit tests and examples) in **mp-units** repository,
-in **mp-units** repository, you should:
+you should:
 
-1. Add remotes of additional Conan dependencies.
+1. Use the *CMakeLists.txt* from the top-level directory.
-2. Use the *CMakeLists.txt* from the top-level directory.
+2. Run Conan with `CONAN_RUN_TESTS`_ = ``True``
-3. Obtain Python dependencies.
+   (use ``-o build_docs=False`` if you want to skip the documentation generation).
-4. Run Conan with `CONAN_RUN_TESTS`_ = ``True``.
+
+.. code-block:: shell
+
+    git clone https://github.com/mpusz/units.git && cd units
+    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -e mp-units:CONAN_RUN_TESTS=True -o build_docs=False -b outdated -u
+    conan build .
+
+The above will download and install all of the dependencies needed for the development of the library,
+build all of the source code and run unit tests.
+
+If you prefer to build the project via CMake rather then Conan, then you should replace the last ``conan build .``
+step with the explicit CMake build:
+
+.. code-block:: shell
+
+    cmake --preset default
+    cmake --build --preset release
+    cmake --build --preset release --target test
+
+
+Building documentation
+----------------------
+
+In case you would like to build the project's documentation, you should:
+
+1. Use the *CMakeLists.txt* from the top-level directory.
+2. Obtain Python dependencies.
+3. Run Conan with `CONAN_RUN_TESTS`_ = ``True``.
 
 .. code-block:: shell
 
     git clone https://github.com/mpusz/units.git && cd units
     pip3 install -r docs/requirements.txt
-    mkdir units/build && cd units/build
+    conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -e mp-units:CONAN_RUN_TESTS=True -b missing
-    conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -e mp-units:CONAN_RUN_TESTS=True -b outdated -u
+    cmake --preset default
-    conan build ..
+    cmake --build --preset release --target documentation
 
-The above will download and install all of the dependencies needed for the development of the library,
+The above will download and install all of the dependencies needed and build the documentation.
-build all of the source code and documentation, and run unit tests.
-
-If you prefer to build the project via CMake rather then Conan, then you should replace the last ``conan build ..``
-step with the CMake build:
-
-.. code-block:: shell
-
-    # ...
-    cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
-    cmake --build .
-    ctest
 
 
 Packaging