From acad4c4dfcb984eccf9e44c6d46f5f42a51ed3bb Mon Sep 17 00:00:00 2001 From: Matt Davis Date: Wed, 23 Nov 2022 12:45:43 -0500 Subject: [PATCH] Documentation updates. --- docs/index.rst | 24 ++++++------------------ docs/install.rst | 22 ++++++++-------------- 2 files changed, 14 insertions(+), 32 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 38d97fb0..b3db3d5d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,7 +48,7 @@ You can quickly play with Pipenv right in your browser: Install Pipenv Today! --------------------- -If you already have Python and pip, you can easily install Pipenv into your home directory:: +The recommended way to install pipenv on most platforms is to install from pypi using ``pip``:: $ pip install --user pipenv @@ -56,9 +56,6 @@ Or, if you're using Fedora 28:: $ sudo dnf install pipenv -It's possible to install Pipenv with Homebrew on MacOS, or with Linuxbrew on Linux systems. However, **this is now discouraged**, because updates to the brewed Python distribution will break Pipenv, and perhaps all virtual environments managed by it. You'll then need to re-install Pipenv at least. If you want to give it a try despite this warning, use:: - - $ brew install pipenv More detailed installation instructions can be found in the :ref:`installing-pipenv` chapter. @@ -66,26 +63,17 @@ More detailed installation instructions can be found in the :ref:`installing-pip .. toctree:: -User Testimonials ------------------ - -**David Gang**— - *This package manager is really awesome. For the first time I know exactly what my dependencies are which I installed and what the transitive dependencies are. Combined with the fact that installs are deterministic, makes this package manager first class, like cargo*. - -**Justin Myles Holmes**— - *Pipenv is finally an abstraction meant to engage the mind instead of merely the filesystem.* - -☤ Pipenv Features +Pipenv Features ----------------- - Enables truly *deterministic builds*, while easily specifying *only what you want*. -- Generates and checks file hashes for locked dependencies. -- Automatically install required Pythons, if ``pyenv`` is available. +- Generates and checks file hashes for locked dependencies when installing from ``Pipfile.lock``. +- Automatically install required Python version when ``pyenv`` is available. - Automatically finds your project home, recursively, by looking for a ``Pipfile``. - Automatically generates a ``Pipfile``, if one doesn't exist. -- Automatically creates a virtualenv in a standard location. +- Automatically creates a virtualenv in a standard customizable location. - Automatically adds/removes packages to a ``Pipfile`` when they are installed or uninstalled. -- Automatically loads ``.env`` files, if they exist. +- Automatically loads ``.env`` files to support customization and overrides. .. include:: quickstart.rst diff --git a/docs/install.rst b/docs/install.rst index ec62edd1..8a506299 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -28,7 +28,7 @@ from your command line. You can check this by simply running:: $ python --version -You should get some output like ``3.6.2``. If you do not have Python, please +You should get some output like ``3.10.8``. If you do not have Python, please install the latest 3.x version from `python.org`_ or refer to the `Installing Python`_ section of *The Hitchhiker's Guide to Python*. @@ -50,7 +50,7 @@ Additionally, you'll need to make sure you have pip available. You can check this by running:: $ pip --version - pip 9.0.1 + pip 22.3.1 If you installed Python from source, with an installer from `python.org`_, via `Homebrew`_ or via `Linuxbrew`_ you should already have pip. If you're on Linux and installed using your OS package manager, you may have to `install pip `_ separately. @@ -70,14 +70,7 @@ Homebrew/Linuxbrew installer takes care of pip for you. ☤ Installing Pipenv =================== -Pipenv is a dependency manager for Python projects. If you're familiar -with Node\.js's `npm`_ or Ruby's `bundler`_, it is similar in spirit to those -tools. While pip can install Python packages, Pipenv is recommended as -it's a higher-level tool that simplifies dependency management for common use -cases. - -.. _npm: https://www.npmjs.com/ -.. _bundler: http://bundler.io/ +It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv``. ☤ Isolated Installation of Pipenv with Pipx @@ -252,12 +245,13 @@ have access to your installed packages with ``$ pipenv shell``. =========================== - Pipenv automatically maps projects to their specific virtualenvs. -- The virtualenv is stored globally with the name of the project’s root directory plus the hash of the full path to the project's root (e.g., ``my_project-a3de50``). -- If you change your project's path, you break such a default mapping and pipenv will no longer be able to find and to use the project's virtualenv. -- You might want to set ``export PIPENV_VENV_IN_PROJECT=1`` in your .bashrc/.zshrc (or any shell configuration file) for creating the virtualenv inside your project's directory, avoiding problems with subsequent path changes. +- By default, the virtualenv is stored globally with the name of the project’s root directory plus the hash of the full path to the project's root (e.g., ``my_project-a3de50``). +- Should you change your project's path, you break such a default mapping and pipenv will no longer be able to find and to use the project's virtualenv. +- Customize this behavior with ``PIPENV_CUSTOM_VENV_NAME`` environment variable. +- You might also prefer to set ``PIPENV_VENV_IN_PROJECT=1`` in your .env or .bashrc/.zshrc (or other shell configuration file) for creating the virtualenv inside your project's directory. ☤ Next steps ============ -Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨ +Congratulations, you now know how to get started with pipenv, for additional details refer to the basic and advanced documentation. ✨ 🍰 ✨