Merge pull request pypa#7859 from pradyunsg/docs/deep-dive-cli

Architecture Documentation: CLI deep dive

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:/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)

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