From f9bd4afcf3298b4bf6eaca8ee478da58abca5a84 Mon Sep 17 00:00:00 2001
From: Pradyun Gedam <3275593+pradyunsg@users.noreply.github.com>
Date: Thu, 24 Sep 2020 02:00:24 +0530
Subject: [PATCH] Merge pull request #7859 from pradyunsg/docs/deep-dive-cli

Architecture Documentation: CLI deep dive
---
 .../architecture/command-line-interface.rst   | 57 +++++++++++++++++++
 docs/html/development/architecture/index.rst  |  1 +
 2 files changed, 58 insertions(+)
 create mode 100644 docs/html/development/architecture/command-line-interface.rst

diff --git a/docs/html/development/architecture/command-line-interface.rst b/docs/html/development/architecture/command-line-interface.rst
new file mode 100644
index 00000000000..9bfa9119258
--- /dev/null
+++ b/docs/html/development/architecture/command-line-interface.rst
@@ -0,0 +1,57 @@
+======================
+Command Line Interface
+======================
+
+The ``pip._internal.cli`` package is responsible for processing and providing
+pip's command line interface. This package handles:
+
+* CLI option definition and parsing
+* autocompletion
+* dispatching to the various commands
+* utilities like progress bars and spinners
+
+.. note::
+
+    This section of the documentation is currently being written. pip
+    developers welcome your help to complete this documentation. If you're
+    interested in helping out, please let us know in the
+    `tracking issue <https://github.com/pypa/pip/issues/6831>`_.
+
+
+.. _cli-overview:
+
+Overview
+========
+
+A ``ConfigOptionParser`` instance is used as the "main parser",
+for parsing top level args.
+
+``Command`` then uses another ``ConfigOptionParser`` instance, to parse command-specific args.
+
+* TODO: How & where options are defined
+  (cmdoptions, command-specific files).
+
+* TODO: How & where arguments are processed.
+  (main_parser, command-specific parser)
+
+* TODO: How processed arguments are accessed.
+  (attributes on argument to ``Command.run()``)
+
+* TODO: How configuration and CLI "blend".
+  (implemented in ``ConfigOptionParser``)
+
+* TODO: progress bars and spinners
+
+* TODO: quirks / standard practices / broad ideas.
+  (avoiding lists in option def'n, special cased option value types,
+  )
+
+
+Future Refactoring Ideas
+========================
+
+* Change option definition to be a more declarative, consistent, static
+  data-structure, replacing the current ``partial(Option, ...)`` form
+* Move progress bar and spinner to a ``cli.ui`` subpackage
+* Move all ``Command`` classes into a ``cli.commands`` subpackage
+  (including base classes)
diff --git a/docs/html/development/architecture/index.rst b/docs/html/development/architecture/index.rst
index 417edf4e9e9..050c2fc45eb 100644
--- a/docs/html/development/architecture/index.rst
+++ b/docs/html/development/architecture/index.rst
@@ -26,6 +26,7 @@ Architecture of pip's internals
     anatomy
     configuration-files
     package-finding
+    command-line-interface
     upgrade-options