Merge pull request #10009 from pradyunsg/new-getting-started-and-inst…

…allation

docs/html/conf.py

@@ -30,7 +30,7 @@
 
 # General information about the project.
 project = "pip"
-copyright = "2008-2020, PyPA"
+copyright = "The pip developers"
 
 # Find the version and release information.
 # We have a single source of truth for our version number: pip's __init__.py file.

docs/html/getting-started.md

@@ -0,0 +1,104 @@
+# Getting Started
+
+To get started with using pip, you should [install Python] on your system.
+
+[install Python]: https://realpython.com/installing-python/
+
+## Ensure you have a working pip
+
+As a first step, you should check that you have a working Python with pip
+installed. This can be done by running the following commands and making
+sure that the output looks similar.
+
+```{pip-cli}
+$ python --version
+Python 3.N.N
+$ pip --version
+pip X.Y.Z from ... (python 3.N.N)
+```
+
+If that worked, congratulations! You have a working pip in your environment.
+
+If you got output that does not look like the sample above, please read
+the {doc}`installation` page. It provides guidance on how to install pip
+within a Python environment that doesn't have it.
+
+## Common tasks
+
+### Install a package
+
+```{pip-cli}
+$ pip install sampleproject
+[...]
+Successfully installed sampleproject
+```
+
+By default, pip will fetch packages from [Python Package Index][PyPI], a
+repository of software for the Python programming language where anyone can
+upload packages.
+
+[PyPI]: https://pypi.org/
+
+### Install a package from GitHub
+
+```{pip-cli}
+$ pip install git+https://github.com/pypa/sampleproject.git@main
+[...]
+Successfully installed sampleproject
+```
+
+See {ref}`VCS Support` for more information about this syntax.
+
+### Install a package from a distribution file
+
+pip can install directly from distribution files as well. They come in 2 forms:
+
+- {term}`source distribution <Source Distribution (or "sdist")>` (usually shortened to "sdist")
+- {term}`wheel distribution <Wheel>` (usually shortened to "wheel")
+
+```{pip-cli}
+$ pip install sampleproject-1.0.tar.gz
+[...]
+Successfully installed sampleproject
+$ pip install sampleproject-1.0-py3-none-any.whl
+[...]
+Successfully installed sampleproject
+```
+
+### Install multiple packages using a requirements file
+
+Many Python projects use {file}`requirements.txt` files, to specify the
+list of packages that need to be installed for the project to run. To install
+the packages listed in that file, you can run:
+
+```{pip-cli}
+$ pip install -r requirements.txt
+[...]
+Successfully installed sampleproject
+```
+
+### Upgrade a package
+
+```{pip-cli}
+$ pip install --upgrade sampleproject
+Uninstalling sampleproject:
+   [...]
+Proceed (y/n)? y
+Successfully uninstalled sampleproject
+```
+
+### Uninstall a package
+
+```{pip-cli}
+$ pip uninstall sampleproject
+Uninstalling sampleproject:
+   [...]
+Proceed (y/n)? y
+Successfully uninstalled sampleproject
+```
+
+## Next Steps
+
+It is recommended to learn about what virtual environments are and how to use
+them. This is covered in the ["Installing Packages"](pypug:tutorials/installing-packages)
+tutorial on packaging.python.org.

docs/html/index.md

@@ -10,8 +10,8 @@ install packages from the [Python Package Index][pypi] and other indexes.
 ```{toctree}
 :hidden:
 
-quickstart
-installing
+getting-started
+installation
 user_guide
 cli/index
 ```
@@ -29,7 +29,7 @@ GitHub <https://github.com/pypa/pip>
 
 If you want to learn about how to use pip, check out the following resources:
 
-- [Quickstart](quickstart)
+- [Getting Started](getting-started)
 - [Python Packaging User Guide](https://packaging.python.org)
 
 If you find bugs, need help, or want to talk to the developers, use our mailing

docs/html/installation.md

@@ -0,0 +1,78 @@
+# Installation
+
+Usually, pip is automatically installed if you are:
+
+- working in a
+  {ref}`virtual environment <pypug:Creating and using Virtual Environments>`
+- using Python downloaded from [python.org](https://www.python.org)
+- using Python that has not been modified by a redistributor to remove
+  {mod}`ensurepip`
+
+## Supported Methods
+
+If your Python environment does not have pip installed, there are 2 mechanisms
+to install pip supported directly by pip's maintainers:
+
+- [`ensurepip`](#using-ensurepip)
+- [`get-pip.py`](#using-get-pip-py)
+
+### `ensurepip`
+
+Python comes with an {mod}`ensurepip` module[^python], which can install pip in
+a Python environment.
+
+```{pip-cli}
+$ python -m ensurepip --upgrade
+```
+
+More details about how {mod}`ensurepip` works and how it can be used, is
+available in the standard library documentation.
+
+### `get-pip.py`
+
+This is a Python script that uses some bootstrapping logic to install
+pip.
+
+- Download the script, from <https://bootstrap.pypa.io/get-pip.py>.
+- Open a terminal/command prompt, `cd` to the folder containing the
+  `get-pip.py` file and run:
+
+  ```{pip-cli}
+  $ python get-pip.py
+  ```
+
+More details about this script can be found in [pypa/get-pip]'s README.
+
+[pypa/get-pip]: https://github.com/pypa/get-pip
+
+## Alternative Methods
+
+Depending on how you installed Python, there might be other mechanisms
+available to you for installing pip such as
+{ref}`using Linux package managers <pypug:installing pip/setuptools/wheel with linux package managers>`.
+
+These mechanisms are provided by redistributors of pip, who may have modified
+pip to change its behaviour. This has been a frequent source of user confusion,
+since it causes a mismatch between documented behaviour in this documentation
+and how pip works after those modifications.
+
+If you face issues when using Python and pip installed using these mechanisms,
+it is recommended to request for support from the relevant provider (eg: Linux
+distro community, cloud provider support channels, etc).
+
+## Compatibility
+
+The current version of pip works on:
+
+- Windows, Linux and MacOS.
+- CPython 3.6, 3.7, 3.8, 3.9 and latest PyPy3.
+
+pip is tested to work on the latest patch version of the Python interpreter,
+for each of the minor versions listed above. Previous patch versions are
+supported on a best effort approach.
+
+pip's maintainers do not provide support for users on older versions of Python,
+and these users should request for support from the relevant provider
+(eg: Linux distro community, cloud provider support channels, etc).
+
+[^python]: The `ensurepip` module was added to the Python standard library in Python 3.4.