[2492] Add new page to document installation methods

docs/conf.py

@@ -17,6 +17,7 @@
 import string
 from pathlib import Path
 
+import tomli
 from pkg_resources import get_distribution
 
 CURRENT_DIR = Path(__file__).parent
@@ -31,6 +32,14 @@ def make_pypi_svg(version: str) -> None:
         f.write(svg)
 
 
+def get_requires_python() -> str:
+    PROJECT_ROOT: Path = CURRENT_DIR.parent
+    pyproject_path: Path = PROJECT_ROOT / "pyproject.toml"
+    with open(str(pyproject_path), "rb") as f:
+        pyproject_toml = tomli.load(f)
+    return pyproject_toml["project"]["requires-python"]
+
+
 # Necessary so Click doesn't hit an encode error when called by
 # sphinxcontrib-programoutput on Windows.
 os.putenv("pythonioencoding", "utf-8")
@@ -112,7 +121,10 @@ def make_pypi_svg(version: str) -> None:
 ]
 
 # Optional MyST Syntaxes
-myst_enable_extensions = []
+myst_enable_extensions = ["substitution"]
+
+# Substitutions to be made in the documentation using MyST
+myst_substitutions = {"SUPPORTED_PYTHON_VERSION": get_requires_python()}
 
 # -- Options for HTML output -------------------------------------------------
 

docs/getting_started.md

@@ -16,13 +16,17 @@ Also, you can try out _Black_ online for minimal fuss on the
 
 ## Installation
 
-_Black_ can be installed by running `pip install black`. It requires Python 3.8+ to run.
-If you want to format Jupyter Notebooks, install with `pip install "black[jupyter]"`.
+_Black_ can be installed by running `pip install black`. It requires Python
+{{ SUPPORTED_PYTHON_VERSION }} to run. If you want to format Jupyter Notebooks, install
+with `pip install "black[jupyter]"`.
 
 If you can't wait for the latest _hotness_ and want to install from GitHub, use:
 
 `pip install git+https://github.com/psf/black`
 
+For more ways to install _Black_, check
+[Ways to install Black](./usage_and_configuration/ways_to_install_black.md)
+
 ## Basic usage
 
 To get started right away with sensible defaults:

docs/usage_and_configuration/index.md

@@ -5,6 +5,7 @@
 hidden:
 ---
 
+ways_to_install_black
 the_basics
 file_collection_and_discovery
 black_as_a_server
@@ -20,8 +21,10 @@ purposefully limited.
 Using many of these more advanced features of _Black_ will require some configuration.
 Configuration that will either live on the command line or in a TOML configuration file.
 
-This section covers features of _Black_ and configuring _Black_ in detail:
+This section covers installation methods, features of _Black_, and configuring _Black_
+in detail:
 
+- {doc}`Ways to install Black <./ways_to_install_black>`
 - {doc}`The basics <./the_basics>`
 - {doc}`File collection and discovery <file_collection_and_discovery>`
 - {doc}`Black as a server (blackd) <./black_as_a_server>`

docs/usage_and_configuration/ways_to_install_black.md

@@ -0,0 +1,53 @@
+# Ways to install Black
+
+There are several ways you can install _Black_. If you're looking to integrate _Black_
+with different editors and environments, check the
+[Integrations](../integrations/index.md) section instead.
+
+## Install from PyPI
+
+To install the latest release of _Black_ from [PyPI](https://pypi.org/project/black/)
+(Requires Python {{ SUPPORTED_PYTHON_VERSION }}), use:
+
+`pip install black`
+
+_Black_ also publishes a number of extras. These are optional modules, designed to add
+functionality to the core _Black_ package.
+
+| extra    | Description                                                   | command                       |
+| -------- | ------------------------------------------------------------- | ----------------------------- |
+| jupyter  | Allows formatting of Jupyter notebooks                        | `pip install black[jupyter]`  |
+| d        | Run _Black_ as a [server](./black_as_a_server.md)             | `pip install black[d]`        |
+| colorama | Enables colored diffs in Windows environments                 | `pip install black[colorama]` |
+| uvloop   | Speeds up _Black_ when concurrently formatting multiple files | `pip install black[uvloop]`   |
+
+A _Black_ release currently offers three types of artifacts via PyPI, as outlined in the
+[Release Process](../contributing/release_process.md):
+
+1. The source distribution of the release
+2. Generic Python wheel, meant for use on any Python supported platform
+3. Platform and Python version specific wheels that offer significantly improved
+   performance, compiled using [mypyc](https://mypyc.readthedocs.io/)
+
+By default, `pip` will prefer a compatible wheel and revert to the source distribution
+if no such wheels are found, as outlined in
+[Python documentation](https://packaging.python.org/en/latest/tutorials/installing-packages/#source-distributions-vs-wheels).
+
+## Install from GitHub
+
+To install the latest commit of _Black_ from the GitHub 'main' branch, use:
+
+`pip install git+https://github.com/psf/black`
+
+## Get native binaries from GitHub
+
+[GitHub Releases](https://github.com/psf/black/releases) for _Black_ contain
+self-contained, native binaries for multiple platforms (built using PyInstaller). This
+allows you to download the executable for your platform and run _Black_ without a Python
+runtime installed.
+
+## Black Docker images
+
+Official _Black_ Docker images are available on
+[Docker Hub](https://hub.docker.com/r/pyfound/black). For more information on its usage,
+check the [Black Docker image](./black_docker_image) section.