Add the JSON report to html/man documentation and add NEWS entry!

Author: cosmicexplorer

Diff for: docs/html/cli/pip_download.rst

@@ -45,6 +45,12 @@ them. Generic dependencies (e.g. universal wheels, or dependencies with no
 platform, abi, or implementation constraints) will still match an over-
 constrained download requirement.
 
+``pip download --report output.json`` is an experimental feature which writes a :ref:`JSON report` of the
+inputs and outputs of pip's internal resolution process to ``output.json``. This can be useful to
+generate a lockfile, check whether transitive dependencies would introduce a conflict, or download
+packages directly from download URLs without having to traverse PyPI again. The ``--dry-run`` option
+can be used in conjunction to just produce a JSON report without actually downloading any packages,
+which is faster.
 
 
 Options
@@ -224,3 +230,17 @@ Examples
             --implementation cp ^
             --abi cp36m --abi cp36 --abi abi3 --abi none ^
             SomePackage
+
+#. Generate a JSON report of the inputs and outputs of pip's internal resolution process with ``--report`` to ``pip-resolve.json``. See the documentation for :ref:`the JSON report <JSON report>`.
+
+   .. tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         $ python -m pip download --dry-run --report pip-resolve.json SomePackage
+
+   .. tab:: Windows
+
+      .. code-block:: shell
+
+         C:> py -m pip download --dry-run --report pip-resolve.json SomePackage

Diff for: docs/html/topics/dependency-resolution.md

@@ -163,9 +163,9 @@ will avoid performing dependency resolution during deployment.
 
 ## Dealing with dependency conflicts
 
-This section provides practical suggestions to pip users who encounter
-a `ResolutionImpossible` error, where pip cannot install their specified
-packages due to conflicting dependencies.
+This section provides practical suggestions to pip users who encounter a `ResolutionImpossible`
+error, where pip cannot install their specified packages due to conflicting dependencies. Note that
+the {ref}`JSON report` may offer more debugging information.
 
 ### Understanding your error message