Merge pull request #7908 from NoahGorny/extract-supported-req-file-option-docs

Extract supported req file option docs

Author: pradyunsg

docs/html/reference/pip_install.rst

@@ -156,18 +156,7 @@ To interpret the requirements file in UTF-8 format add a comment
 
 The following options are supported:
 
-  *  :ref:`-i, --index-url <install_--index-url>`
-  *  :ref:`--extra-index-url <install_--extra-index-url>`
-  *  :ref:`--no-index <install_--no-index>`
-  *  :ref:`-c, --constraint <install_--constraint>`
-  *  :ref:`-r, --requirement <install_--requirement>`
-  *  :ref:`-e, --editable <install_--editable>`
-  *  :ref:`-f, --find-links <install_--find-links>`
-  *  :ref:`--no-binary <install_--no-binary>`
-  *  :ref:`--only-binary <install_--only-binary>`
-  *  :ref:`--require-hashes <install_--require-hashes>`
-  *  :ref:`--pre <install_--pre>`
-  *  :ref:`--trusted-host <--trusted-host>`
+.. pip-requirements-file-options-ref-list::
 
 For example, to specify :ref:`--no-index <install_--no-index>` and two
 :ref:`--find-links <install_--find-links>` locations:

docs/pip_sphinxext.py

@@ -9,7 +9,8 @@
 from docutils.statemachine import ViewList
 
 from pip._internal.cli import cmdoptions
-from pip._internal.commands import create_command
+from pip._internal.commands import commands_dict, create_command
+from pip._internal.req.req_file import SUPPORTED_OPTIONS
 
 
 class PipCommandUsage(rst.Directive):
@@ -108,9 +109,50 @@ def process_options(self):
         )
 
 
+class PipReqFileOptionsReference(PipOptions):
+
+    def determine_opt_prefix(self, opt_name):
+        for command in commands_dict:
+            cmd = create_command(command)
+            if cmd.cmd_opts.has_option(opt_name):
+                return command
+
+        raise KeyError('Could not identify prefix of opt {}'.format(opt_name))
+
+    def process_options(self):
+        for option in SUPPORTED_OPTIONS:
+            if getattr(option, 'deprecated', False):
+                continue
+
+            opt = option()
+            opt_name = opt._long_opts[0]
+            if opt._short_opts:
+                short_opt_name = '{}, '.format(opt._short_opts[0])
+            else:
+                short_opt_name = ''
+
+            if option in cmdoptions.general_group['options']:
+                prefix = ''
+            else:
+                prefix = '{}_'.format(self.determine_opt_prefix(opt_name))
+
+            self.view_list.append(
+                '  *  :ref:`{short}{long}<{prefix}{opt_name}>`'.format(
+                    short=short_opt_name,
+                    long=opt_name,
+                    prefix=prefix,
+                    opt_name=opt_name
+                ),
+                "\n"
+            )
+
+
 def setup(app):
     app.add_directive('pip-command-usage', PipCommandUsage)
     app.add_directive('pip-command-description', PipCommandDescription)
     app.add_directive('pip-command-options', PipCommandOptions)
     app.add_directive('pip-general-options', PipGeneralOptions)
     app.add_directive('pip-index-options', PipIndexOptions)
+    app.add_directive(
+        'pip-requirements-file-options-ref-list', PipReqFileOptionsReference
+    )

news/7908.doc

@@ -0,0 +1,2 @@
+List of options supported in requirements file are extracted from source of truth,
+instead of being maintained manually.

src/pip/_internal/cli/cmdoptions.py

@@ -832,6 +832,10 @@ def _handle_no_use_pep517(option, opt, value, parser):
     action='store_true',
     help=SUPPRESS_HELP,
 )  # type: Callable[..., Option]
+# TODO: Move into a class that inherits from partial, currently does not
+# work as mypy complains functools.partial is a generic class.
+# This way we know we can ignore this option in docs auto generation
+setattr(always_unzip, 'deprecated', True)
 
 
 def _handle_merge_hash(option, opt_str, value, parser):