lock: add documentation

Author: sbidoul

docs/html/cli/index.md

@@ -23,6 +23,13 @@ pip_freeze
 pip_check
 ```
 
+```{toctree}
+:maxdepth: 1
+:caption: Resolving dependencies
+
+pip_lock
+```
+
 ```{toctree}
 :maxdepth: 1
 :caption: Handling Distribution Files

docs/html/cli/pip_lock.rst

@@ -0,0 +1,50 @@
+
+.. _`pip lock`:
+
+========
+pip lock
+========
+
+
+
+Usage
+=====
+
+.. tab:: Unix/macOS
+
+   .. pip-command-usage:: lock "python -m pip"
+
+.. tab:: Windows
+
+   .. pip-command-usage:: lock "py -m pip"
+
+
+Description
+===========
+
+.. pip-command-description:: lock
+
+Options
+=======
+
+.. pip-command-options:: lock
+
+.. pip-index-options:: lock
+
+
+Examples
+========
+
+#. Emit a ``pylock.toml`` for the the project in the current directory
+
+   .. tab:: Unix/macOS
+
+      .. code-block:: shell
+
+         python -m pip lock -e .
+
+   .. tab:: Windows
+
+      .. code-block:: shell
+
+         py -m pip lock -e .

docs/man/commands/lock.rst

@@ -0,0 +1,20 @@
+:orphan:
+
+========
+pip-lock
+========
+
+Description
+***********
+
+.. pip-command-description:: lock
+
+Usage
+*****
+
+.. pip-command-usage:: lock
+
+Options
+*******
+
+.. pip-command-options:: lock

docs/man/index.rst

@@ -34,6 +34,9 @@ pip-uninstall(1)
 pip-freeze(1)
     Output installed packages in requirements format.
 
+pip-lock(1)
+    Generate a lock file for requirements and their dependencies.
+
 pip-list(1)
     List installed packages.
 

src/pip/_internal/commands/lock.py

@@ -26,22 +26,24 @@
 
 class LockCommand(RequirementCommand):
     """
-    Lock packages from:
+    EXPERIMENTAL - Lock packages and their dependencies from:
 
     - PyPI (and other indexes) using requirement specifiers.
     - VCS project urls.
     - Local project directories.
     - Local or remote source archives.
 
-    pip also supports locking from "requirements files", which provide
-    an easy way to specify a whole environment to be installed.
+    pip also supports locking from "requirements files", which provide an easy
+    way to specify a whole environment to be installed.
+
+    The generated lock file is only guaranteed to be valid for the current
+    python version and platform.
     """
 
     usage = """
+      %prog [options] [-e] <local project path> ...
       %prog [options] <requirement specifier> [package-index-options] ...
       %prog [options] -r <requirements file> [package-index-options] ...
-      %prog [options] [-e] <vcs project url> ...
-      %prog [options] [-e] <local project path> ...
       %prog [options] <archive url/path> ..."""
 
     def add_options(self) -> None: