Review for multiple missing items (#4065)

* adding proxies confs information

* adding information of CMakeToolchain find_paths block

* deployer-package negations

* adding system_requirements() section for build-time

* clarify auto_generate=True argument for VirtualBuildEnv

* add package-type for header-only libraries

* adding transitive_headers in the tutorial

Author: memsharded

README.md

@@ -1,7 +1,5 @@
 Documentation for Conan C/C++ package manager: https://conan.io
 
-[![Build Status](https://travis-ci.org/conan-io/docs.svg?branch=master)](https://travis-ci.org/conan-io/docs)
-
 How to build
 ============
 

reference/commands/install.rst

@@ -145,9 +145,11 @@ It is possible to also invoke the package recipes ``deploy()`` method with the `
 .. code-block:: bash
 
     # Execute deploy() method of every recipe that defines it
-    $ conan install --requires=pkg/0.1 --deployer-package=*
+    $ conan install --requires=pkg/0.1 --deployer-package="*"
     # Execute deploy() method only for "pkg" (any version) recipes
-    $ conan install --requires=pkg/0.1 --deployer-package=pkg/*
+    $ conan install --requires=pkg/0.1 --deployer-package="pkg/*"
+    # Execute deploy() method for all packages except the "zlib" (transitive dep) one
+    $ conan install --requires=pkg/0.1 --deployer-package="*" --deployer-package="~zlib/*"
 
 The ``--deployer-package`` argument is a pattern and accepts multiple values, all package references matching any of the defined patterns will execute its ``deploy()`` method.
 This includes negated patterns, where for example ``--deployer-package=~pkg/*`` will execute the ``deploy()`` method for all packages except for that of the ``pkg`` recipe.

reference/conanfile/methods/requirements.rst

@@ -88,7 +88,8 @@ when we want to use different versions of the same package during the build.
 transitive_headers
 ~~~~~~~~~~~~~~~~~~
 
-If ``True`` the headers of the dependency will be visible downstream.
+If ``True`` the headers of the dependency will be visible downstream. 
+Read more about this trait in the :ref:`tutorial for headers transitivity<tutorial_create_packages_headers_transitivity>`.
 
 transitive_libs
 ~~~~~~~~~~~~~~~

reference/conanfile/methods/system_requirements.rst

@@ -101,3 +101,17 @@ On the other hand, the ``report-installed`` mode will do a check if the package
             ]
         }
     }
+
+
+Build time system requirements 
+------------------------------
+
+In some scenarios, it might be possible that some system-requirements are only necessary exclusively at
+build time. For those scenarios, there are 2 possibilities:
+
+- Add the logic that install the build-time system requirements in a different method, like the ``build()``
+  method or the ``generate()`` method.
+- Wrap the installation and logic for the build-time system requirement in its own package recipe, and use
+  that recipe as a ``tool_requires``. 
+  
+There are examples :ref:`for build-time system requirements in this section <examples_tools_system_consuming_system_packages>`

reference/config_files/global_conf.rst

@@ -33,36 +33,6 @@ To list all the possible configurations available, run :command:`conan config li
     :command: conan config list
 
 
-Description of configurations
-+++++++++++++++++++++++++++++
-
-core.cache:storage_path
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Absolute path to a folder where the Conan packages and the database of the packages will be stored.
-This folder will be the heaviest Conan storage folder, as it stores the binary packages downloaded or created.
-
-.. code-block:: text
-    :caption: *global.conf*
-
-    core.cache:storage_path = C:\Users\danielm\my_conan_storage_folder
-
-**Default value:** ``<CONAN_HOME>/p``
-
-core.download:download_cache
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Absolute path to a folder where the Conan packages will be stored *compressed*.
-This is useful to avoid recurrent downloads of the same packages, especially in CI.
-
-.. code-block:: text
-    :caption: *global.conf*
-
-    core.download:download_cache = C:\Users\danielm\my_download_cache
-
-**Default value:** Not defined.
-
-
 User/Tools configurations
 -------------------------
 
@@ -244,6 +214,65 @@ For instance:
   (And even then, properly scoping the conf to only the required recipes is a good idea)
   or if you are using it for development purposes
 
+Proxies
++++++++
+
+There are 3 ``confs`` that can define proxies information:
+
+.. code-block:: bash
+
+  $ conan config list proxies
+  core.net.http:clean_system_proxy: If defined, the proxies system env-vars will be discarded
+  core.net.http:no_proxy_match: List of urls to skip from proxies configuration
+  core.net.http:proxies: Dictionary containing the proxy configuration
+
+The ``core.net.http:proxies`` dictionary is passed to the underlying ``python-requests`` library, to the "proxies" argument
+as described in the `python-requests documentation <https://requests.readthedocs.io/en/latest/user/advanced/#proxies>`_
+
+The ``core.net:no_proxy_match`` is a list of URL patterns, like:
+
+.. code-block:: ini
+
+  core.net.http:no_proxy_match = ["http://someurl.com/*"]
+
+
+for URLs to be excluded from the ``proxies`` configuration. That means that all URLs that are referenced that matches any
+of those patterns will not receive the ``proxies`` definition. Note the ``*`` in the pattern is necessary for the match.
+
+If ``core.net.http:clean_system_proxy`` is ``True``, then the environment variables ``"http_proxy", "https_proxy", "ftp_proxy", "all_proxy", "no_proxy"``,
+will be temporary removed from the environment, so they are not taken into account when resolving proxies.
+
+
+
+Storage configurations
+----------------------
+
+core.cache:storage_path
++++++++++++++++++++++++
+
+Absolute path to a folder where the Conan packages and the database of the packages will be stored.
+This folder will be the heaviest Conan storage folder, as it stores the binary packages downloaded or created.
+
+.. code-block:: text
+    :caption: *global.conf*
+
+    core.cache:storage_path = C:\Users\danielm\my_conan_storage_folder
+
+**Default value:** ``<CONAN_HOME>/p``
+
+core.download:download_cache
+++++++++++++++++++++++++++++
+
+Absolute path to a folder where the Conan packages will be stored *compressed*.
+This is useful to avoid recurrent downloads of the same packages, especially in CI.
+
+.. code-block:: text
+    :caption: *global.conf*
+
+    core.download:download_cache = C:\Users\danielm\my_download_cache
+
+**Default value:** Not defined.
+
 
 UX confs
 --------

reference/tools/cmake/cmaketoolchain.rst

@@ -638,6 +638,20 @@ dependencies can be found. For this case, it should be possible to do something
 
 For more information about these blocks, please have a look at the source code.
 
+Finding dependencies paths
+--------------------------
+
+The generated ``conan_toolchain.cmake`` contains information in its ``find_paths`` block for variables such as
+``CMAKE_PROGRAM_PATH``, ``CMAKE_LIBRARY_PATH``, ``CMAKE_INCLUDE_PATH`` and others, that allow CMake to run
+``find_program()``, ``find_file()`` and other special "finder" routines that find artifacts without a explicit
+package and targets definition via the overall recommended ``find_package()``.
+
+With the new incubating ``CMakeConfigDeps``, the ``conan_toolchain.cmake`` block ``find_paths`` no longer
+defines the information itself, but it just loads a new file generated by the ``CMakeConfigDeps`` generator, the
+``conan_cmakedeps_paths.cmake`` file. This way, the responsibility for creating information about dependencies is
+the ``CMakeConfigDeps`` generator, and that new file can be used in some scenarios in which passing a toolchain
+is not possible.
+
 
 Cross building
 --------------

reference/tools/env/virtualbuildenv.rst

@@ -42,6 +42,30 @@ And it can also be fully instantiated in the conanfile ``generate()`` method:
             ms.generate()
 
 
+Note that instantiating the ``VirtualBuildEnv()`` generator without later calling the ``generate()`` method,
+which is intended only for the ``generate()`` recipe method, will inhibit the creation of environment files.
+
+So something like:
+
+.. code-block:: python
+
+    ms = VirtualBuildEnv(self)
+    my_env_var = ms.vars().get("MY_ENV_VAR")
+    # does not create conanbuildenv.sh|.bat files
+
+
+will stop creating the ``conanbuild.sh|.bat`` and ``conanbuildenv.sh|.bat`` files that are created by default,
+even when ``VirtualBuildEnv`` is not instantiated.
+
+In order to keep creating those files, the ``auto_generate=True`` argument can be passed to the constructor, as:
+
+.. code-block:: python
+
+    ms = VirtualBuildEnv(self, auto_generate=True)
+    my_env_var = ms.vars().get("MY_ENV_VAR")
+    # does create conanbuildenv.sh|.bat files
+
+
 
 Generated files
 ---------------

tutorial/creating_packages/add_dependencies_to_packages.rst

@@ -117,6 +117,43 @@ colour now:
       hello/1.0: __clang_minor__ 1
       hello/1.0: __apple_build_version__ 13160021
 
+.. _tutorial_create_packages_headers_transitivity:
+
+Headers transitivity
+--------------------
+
+By default, Conan assumes that the required dependency headers are an implementation detail of the current package,
+to promote good software engineering practices like low coupling and encapsulation. In the example above, ``fmt``
+is purely an implementation detail in the ``hello/1.0`` package. Consumers of ``hello/1.0`` will not know anything
+about ``fmt``, or has access to its headers, if a consumer of ``hello/1.0`` would try to add a ``#include <fmt/color.h>``,
+it will fail, not being able to find that headers.
+
+But if the public headers of the ``hello/1.0`` package have the ``#include`` to ``fmt`` headers, that means that such
+headers must be propagated down to allow consumers of ``hello/1.0`` to be compiled successfully. As this is not the
+default expected behavior, recipes must declare it as:
+
+.. code-block:: python
+
+    class helloRecipe(ConanFile):
+        name = "hello"
+        version = "1.0"
+
+        def requirements(self):
+            self.requires("fmt/8.1.1", transitive_headers=True)
+
+
+That will propagate the necessary compilation flags and headers ``includedirs`` to the consumers of ``hello/1.0``.
+
+.. note::
+
+  **Best practices**
+
+  If a consumer of ``hello/1.0`` had a direct inclusion to ``fmt`` headers such as ``#include <fmt/color.h>``, then,
+  such a consumer should declare its own ``self.requires("fmt/8.1.1")`` requirement, as that is a direct requirement.
+  In other words, even if the dependency to ``hello/1.0`` was removed from that consumer, it would still depend on ``fmt``,
+  and consequently it cannot abouse the transitivity of the ``fmt`` headers from ``hello``, but declare them explicitly.
+
+
 .. seealso::
 
   - :ref:`Reference for requirements() method <reference_conanfile_methods_requirements>`.

tutorial/creating_packages/other_types_of_packages/header_only_packages.rst

@@ -39,6 +39,8 @@ This is a basic recipe for a header-only recipe:
         exports_sources = "include/*"
         # We can avoid copying the sources to the build folder in the cache
         no_copy_source = True
+        # Important, define the package_type
+        package_type = "header-library"
 
         def package(self):
             # This will also copy the "include" folder
@@ -160,6 +162,8 @@ We have the same header-only library that sums two numbers, but now we have this
         exports_sources = "include/*", "test/*"
         no_copy_source = True
         generators = "CMakeToolchain", "CMakeDeps"
+        # Important, define the package_type
+        package_type = "header-library"
 
         def requirements(self):
             self.test_requires("gtest/1.11.0")