Docs: clarify private deps require requirements.txt, not pyproject.toml

docs/user/faq.rst

@@ -135,6 +135,19 @@ You can also set your project documentation to install your Python project itsel
       * :ref:`faq:Why do I get import errors from libraries depending on C modules?`
 
 
+How do I install private dependencies if my package uses pyproject.toml?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pip does not support environment variable expansion in ``pyproject.toml`` files.
+If your project has private dependencies that require authentication tokens,
+you will need to use a ``requirements.txt`` file instead.
+
+.. seealso::
+
+   :doc:`/guides/private-python-packages`
+      Complete guide on installing private Python packages from Git repositories or repository managers.
+
+
 How do I change behavior when building with Read the Docs?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/user/guides/private-python-packages.rst

@@ -26,6 +26,13 @@ To install a private package from a Git repositories, add the URI to your :ref:`
 
 `Pip automatically  expands <https://pip.pypa.io/en/stable/reference/requirements-file-format/#using-environment-variables>`__ environment variables in POSIX format: using only uppercase letters and ``_``, and including a dollar sign and curly brackets around the name, like ``${API_TOKEN}``.
 
+.. note::
+
+   Environment variable expansion is only supported in ``requirements.txt`` files.
+   If your project uses ``pyproject.toml``,
+   pip does not support expanding environment variables in that format.
+   Use a ``requirements.txt`` file for installing private dependencies instead.
+
 See :doc:`using environment variables in Read the Docs </environment-variables>` for more information.
 
 .. contents:: How to get a personal access token from our supported providers