Minor refactor of Private Python packages page (#11395)

* Minor refactor

* sembr

docs/user/config-file/v2.rst

@@ -130,6 +130,9 @@ Configuration of the Python environment to be used.
 python.install
 ``````````````
 
+Read the Docs uses :doc:`pip <pip:index>` by  default to install your Python packages, however if you are using a :ref:`Conda <config-file/v2:conda>` environment to manage your build, you'll need to use the Conda ``environment`` file instead.
+If you have a commercial plan you can also install :doc:`private dependencies </guides/private-python-packages>`.
+
 List of installation methods of packages and requirements.
 You can have several of the following methods.
 
@@ -158,16 +161,11 @@ Example:
        - requirements: docs/requirements.txt
        - requirements: requirements.txt
 
-.. warning::
-
-  If you are using a :ref:`Conda <config-file/v2:conda>` environment to
-  manage the build, this setting will not have any effect. Instead
-  add the extra requirements to the ``environment`` file of Conda.
-
 Packages
 ''''''''
 
-Install the project using ``pip install`` (recommended) or ``python setup.py install`` (deprecated).
+Install the project using ``pip install``.
+The use of ``python setup.py install`` is deprecated.
 
 The path to the package, relative to the root of the project.
 
@@ -186,15 +184,11 @@ The installation method.
 .. _Extra Requirements: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies
 .. _package dependencies: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#declaring-required-dependency
 
-.. warning::
-
-   You need to install your project with ``pip`` to use ``extra_requirements``.
-
 :Key: ``extra_requirements``
 :Type: ``list``
 :Default: ``[]``
 
-Example:
+For example, to run ``pip install .[docs]``:
 
 .. code-block:: yaml
 
@@ -207,12 +201,6 @@ Example:
          extra_requirements:
            - docs
 
-With the previous settings, Read the Docs will execute the next commands:
-
-.. prompt:: bash $
-
-   pip install .[docs]
-
 conda
 ~~~~~
 

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

@@ -5,7 +5,7 @@ How to install private python packages
 
    This guide is for :doc:`/commercial/index`.
 
-Read the Docs uses :doc:`pip <pip:index>` to install your Python packages.
+Read the Docs uses :ref:`pip <config-file/v2:python.install>` to install your Python packages.
 If you have private dependencies, you can install them from
 a :ref:`private Git repository <guides/private-python-packages:From a Git repository>` or
 a :ref:`private repository manager <guides/private-python-packages:From a repository manager other than PyPI>`.
@@ -15,41 +15,27 @@ From a Git repository
 
 Pip supports installing packages from a :ref:`Git repository <pip:vcs support>` using the URI form:
 
-.. code::
-
-   git+https://gitprovider.com/user/project.git@{version}
-
-Or if your repository is private:
-
-.. code::
-
-   git+https://{token}@gitprovider.com/user/project.git@{version}
+- ``git+https://gitprovider.com/user/project.git@{version}`` (public repository)
+- ``git+https://{token}@gitprovider.com/user/project.git@{version}`` (private repository)
 
-Where ``version`` can be a tag, a branch, or a commit.
-And ``token`` is a personal access token with read only permissions from your provider.
+Where ``version`` can be a tag, a branch, or a commit, and ``token`` is a personal access token with read only permissions from your provider.
 
 .. TODO: We should add the git+ssh form when we support running the ssh-agent in the build step.
 
-To install the package,
-you need to add the URI in your :ref:`requirements file <config-file/v2:Requirements file>`.
-Pip will automatically expand environment variables in your URI,
-so you don't have to hard code the token in the URI.
-See :doc:`using environment variables in Read the Docs </environment-variables>` for more information.
+To install a private package from a Git repositories, add the URI to your :ref:`requirements file <config-file/v2:Requirements file>`. Make sure to use an environment variable for the token, so you don't have to hard code it in the URI.
 
-.. note::
+`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}``.
 
-   You have to use the POSIX format for variable names (only uppercase letters and ``_`` are allowed),
-   and including a dollar sign and curly brackets around the name (``${API_TOKEN}``)
-   for `pip to be able to recognize them <https://pip.pypa.io/en/stable/reference/requirements-file-format/#using-environment-variables>`__.
+See :doc:`using environment variables in Read the Docs </environment-variables>` for more information.
 
-Below you can find how to get a personal access token from our supported providers.
-We will be using environment variables for the token.
+.. contents:: How to get a personal access token from our supported providers
+   :local:
 
 GitHub
 ~~~~~~
 
 You need to create a personal access token with the ``repo`` scope.
-Check the `GitHub documentation <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token>`__
+Follow the `GitHub documentation <https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line#creating-a-token>`__
 on how to create a personal token.
 
 URI example:
@@ -69,22 +55,20 @@ GitLab
 ~~~~~~
 
 You need to create a deploy token with the ``read_repository`` scope for the repository you want to install the package from.
-Check the `GitLab documentation <https://docs.gitlab.com/ee/user/project/deploy_tokens/#creating-a-deploy-token>`__
+Follow the `GitLab documentation <https://docs.gitlab.com/ee/user/project/deploy_tokens/#creating-a-deploy-token>`__
 on how to create a deploy token.
 
-URI example:
+URI example, where ``GITLAB_TOKEN_USER`` is the user from the deploy token you created, not your GitLab user:
 
 .. code::
 
    git+https://${GITLAB_TOKEN_USER}:${GITLAB_TOKEN}@gitlab.com/user/project.git@{version}
 
-Here ``GITLAB_TOKEN_USER`` is the user from the deploy token you created, not your GitLab user.
-
 Bitbucket
 ~~~~~~~~~
 
 You need to create an app password with ``Read repositories`` permissions.
-Check the `Bitbucket documentation <https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html>`__
+Follow the `Bitbucket documentation <https://confluence.atlassian.com/bitbucket/app-passwords-828781300.html>`__
 on how to create an app password.
 
 URI example:
@@ -99,20 +83,16 @@ Here ``BITBUCKET_USER`` is your Bitbucket user.
 
    Bitbucket doesn't support app passwords per repository.
    An app password will grant read access to all repositories the user has access to.
+   You can create a a `machine user <https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html>`__ to give read access only to the repositories you need.
 
 From a repository manager other than PyPI
 -----------------------------------------
 
-Pip by default will install your packages from `PyPI <https://pypi.org/>`__.
-If you are using a repository manager like *pypiserver*, or *Nexus Repository*,
-you need to set the :option:`pip:--index-url` option.
-You have two ways of set that option:
+By default Pip installs your packages from `PyPI <https://pypi.org/>`__.
+If you are using a different repository manager like *pypiserver*, or *Nexus Repository*,
+you need to get the index URL from your repository manager and set the :option:`pip:--index-url` option in one of the following ways:
 
 - Set the ``PIP_INDEX_URL`` :doc:`environment variable in Read the Docs </environment-variables>` with the index URL.
-  See https://pip.pypa.io/en/stable/reference/requirements-file-format#using-environment-variables.
+  See the Requirements File `environment variables <https://pip.pypa.io/en/stable/reference/requirements-file-format#using-environment-variables>`__ reference.
 - Put ``--index-url=https://my-index-url.com/`` at the top of your requirements file.
   See :ref:`pip:requirements-file-format`.
-
-.. note::
-
-   Check your repository manager's documentation to obtain the appropriate index URL.