From a5e720afb121dbe695434ddedc7245ae787f8ad3 Mon Sep 17 00:00:00 2001 From: Sam Date: Mon, 1 Jul 2024 13:11:53 +0300 Subject: [PATCH] Minor refactor of Private Python packages page (#11395) * Minor refactor * sembr --- docs/user/config-file/v2.rst | 24 +++------ docs/user/guides/private-python-packages.rst | 56 +++++++------------- 2 files changed, 24 insertions(+), 56 deletions(-) diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index a2728c7f4bb..583a7d928d7 100644 --- a/docs/user/config-file/v2.rst +++ b/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 ` by default to install your Python packages, however if you are using a :ref:`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 `. + 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 ` 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 ~~~~~ diff --git a/docs/user/guides/private-python-packages.rst b/docs/user/guides/private-python-packages.rst index 3f36be452c4..a37e6e63538 100644 --- a/docs/user/guides/private-python-packages.rst +++ b/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 ` to install your Python packages. +Read the Docs uses :ref:`pip ` to install your Python packages. If you have private dependencies, you can install them from a :ref:`private Git repository ` or a :ref:`private repository manager `. @@ -15,41 +15,27 @@ From a Git repository Pip supports installing packages from a :ref:`Git repository ` 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 `. -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 ` for more information. +To install a private package from a Git repositories, add the URI to your :ref:`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 `__ 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 `__. +See :doc:`using environment variables in Read the Docs ` 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 `__ +Follow the `GitHub documentation `__ 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 `__ +Follow the `GitLab documentation `__ 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 `__ +Follow the `Bitbucket documentation `__ 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 `__ 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 `__. -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 `__. +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 ` with the index URL. - See https://pip.pypa.io/en/stable/reference/requirements-file-format#using-environment-variables. + See the Requirements File `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.