Воркед

venv/Lib/site-packages/pip/_vendor/pygments/sphinxext.py

@@ -5,7 +5,7 @@
     Sphinx extension to generate automatic documentation of lexers,
     formatters and filters.
 
-    :copyright: Copyright 2006-2022 by the Pygments team, see AUTHORS.
+    :copyright: Copyright 2006-2024 by the Pygments team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 
@@ -33,6 +33,8 @@ LEXERDOC = '''
 
     %s
 
+    %s
+
 '''
 
 FMTERDOC = '''
@@ -74,6 +76,8 @@ class PygmentsDoc(Directive):
             out = self.document_formatters()
         elif self.arguments[0] == 'filters':
             out = self.document_filters()
+        elif self.arguments[0] == 'lexers_overview':
+            out = self.document_lexers_overview()
         else:
             raise Exception('invalid argument for "pygmentsdoc" directive')
         node = nodes.compound()
@@ -83,8 +87,72 @@ class PygmentsDoc(Directive):
             self.state.document.settings.record_dependencies.add(fn)
         return node.children
 
+    def document_lexers_overview(self):
+        """Generate a tabular overview of all lexers.
+
+        The columns are the lexer name, the extensions handled by this lexer
+        (or "None"), the aliases and a link to the lexer class."""
+        from pip._vendor.pygments.lexers._mapping import LEXERS
+        from pip._vendor.pygments.lexers import find_lexer_class
+        out = []
+
+        table = []
+
+        def format_link(name, url):
+            if url:
+                return f'`{name} <{url}>`_'
+            return name
+
+        for classname, data in sorted(LEXERS.items(), key=lambda x: x[1][1].lower()):
+            lexer_cls = find_lexer_class(data[1])
+            extensions = lexer_cls.filenames + lexer_cls.alias_filenames
+
+            table.append({
+                'name': format_link(data[1], lexer_cls.url),
+                'extensions': ', '.join(extensions).replace('*', '\\*').replace('_', '\\') or 'None',
+                'aliases': ', '.join(data[2]),
+                'class': f'{data[0]}.{classname}'
+            })
+
+        column_names = ['name', 'extensions', 'aliases', 'class']
+        column_lengths = [max([len(row[column]) for row in table if row[column]])
+                          for column in column_names]
+
+        def write_row(*columns):
+            """Format a table row"""
+            out = []
+            for length, col in zip(column_lengths, columns):
+                if col:
+                    out.append(col.ljust(length))
+                else:
+                    out.append(' '*length)
+
+            return ' '.join(out)
+
+        def write_seperator():
+            """Write a table separator row"""
+            sep = ['='*c for c in column_lengths]
+            return write_row(*sep)
+
+        out.append(write_seperator())
+        out.append(write_row('Name', 'Extension(s)', 'Short name(s)', 'Lexer class'))
+        out.append(write_seperator())
+        for row in table:
+            out.append(write_row(
+                row['name'],
+                row['extensions'],
+                row['aliases'],
+                f':class:`~{row["class"]}`'))
+        out.append(write_seperator())
+
+        return '\n'.join(out)
+
     def document_lexers(self):
         from pip._vendor.pygments.lexers._mapping import LEXERS
+        from pip._vendor import pygments
+        import inspect
+        import pathlib
+
         out = []
         modules = {}
         moduledocstrings = {}
@@ -94,16 +162,40 @@ class PygmentsDoc(Directive):
             self.filenames.add(mod.__file__)
             cls = getattr(mod, classname)
             if not cls.__doc__:
-                print("Warning: %s does not have a docstring." % classname)
+                print(f"Warning: {classname} does not have a docstring.")
             docstring = cls.__doc__
             if isinstance(docstring, bytes):
                 docstring = docstring.decode('utf8')
+
+            example_file = getattr(cls, '_example', None)
+            if example_file:
+                p = pathlib.Path(inspect.getabsfile(pygments)).parent.parent /\
+                    'tests' / 'examplefiles' / example_file
+                content = p.read_text(encoding='utf-8')
+                if not content:
+                    raise Exception(
+                        f"Empty example file '{example_file}' for lexer "
+                        f"{classname}")
+
+                if data[2]:
+                    lexer_name = data[2][0]
+                    docstring += '\n\n    .. admonition:: Example\n'
+                    docstring += f'\n      .. code-block:: {lexer_name}\n\n'
+                    for line in content.splitlines():
+                        docstring += f'          {line}\n'
+
+            if cls.version_added:
+                version_line = f'.. versionadded:: {cls.version_added}'
+            else:
+                version_line = ''
+
             modules.setdefault(module, []).append((
                 classname,
                 ', '.join(data[2]) or 'None',
                 ', '.join(data[3]).replace('*', '\\*').replace('_', '\\') or 'None',
                 ', '.join(data[4]) or 'None',
-                docstring))
+                docstring,
+                version_line))
             if module not in moduledocstrings:
                 moddoc = mod.__doc__
                 if isinstance(moddoc, bytes):
@@ -112,7 +204,7 @@ class PygmentsDoc(Directive):
 
         for module, lexers in sorted(modules.items(), key=lambda x: x[0]):
             if moduledocstrings[module] is None:
-                raise Exception("Missing docstring for %s" % (module,))
+                raise Exception(f"Missing docstring for {module}")
             heading = moduledocstrings[module].splitlines()[4].strip().rstrip('.')
             out.append(MODULEDOC % (module, heading, '-'*len(heading)))
             for data in lexers: