Edit File: sphinxext.py
""" pygments.sphinxext ~~~~~~~~~~~~~~~~~~ Sphinx extension to generate automatic documentation of lexers, formatters and filters. :copyright: Copyright 2006-2025 by the Pygments team, see AUTHORS. :license: BSD, see LICENSE for details. """ import sys from docutils import nodes from docutils.statemachine import ViewList from docutils.parsers.rst import Directive from sphinx.util.nodes import nested_parse_with_titles MODULEDOC = ''' .. module:: %s %s %s ''' LEXERDOC = ''' .. class:: %s :Short names: %s :Filenames: %s :MIME types: %s %s %s ''' FMTERDOC = ''' .. class:: %s :Short names: %s :Filenames: %s %s ''' FILTERDOC = ''' .. class:: %s :Name: %s %s ''' class PygmentsDoc(Directive): """ A directive to collect all lexers/formatters/filters and generate autoclass directives for them. """ has_content = False required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False option_spec = {} def run(self): self.filenames = set() if self.arguments[0] == 'lexers': out = self.document_lexers() elif self.arguments[0] == 'formatters': 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() vl = ViewList(out.split('\n'), source='') nested_parse_with_titles(self.state, vl, node) for fn in self.filenames: 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 = {} for classname, data in sorted(LEXERS.items(), key=lambda x: x[0]): module = data[0] mod = __import__(module, None, None, [classname]) self.filenames.add(mod.__file__) cls = getattr(mod, classname) if not cls.__doc__: 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, version_line)) if module not in moduledocstrings: moddoc = mod.__doc__ if isinstance(moddoc, bytes): moddoc = moddoc.decode('utf8') moduledocstrings[module] = moddoc for module, lexers in sorted(modules.items(), key=lambda x: x[0]): if moduledocstrings[module] is None: 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: out.append(LEXERDOC % data) return ''.join(out) def document_formatters(self): from pip._vendor.pygments.formatters import FORMATTERS out = [] for classname, data in sorted(FORMATTERS.items(), key=lambda x: x[0]): module = data[0] mod = __import__(module, None, None, [classname]) self.filenames.add(mod.__file__) cls = getattr(mod, classname) docstring = cls.__doc__ if isinstance(docstring, bytes): docstring = docstring.decode('utf8') heading = cls.__name__ out.append(FMTERDOC % (heading, ', '.join(data[2]) or 'None', ', '.join(data[3]).replace('*', '\\*') or 'None', docstring)) return ''.join(out) def document_filters(self): from pip._vendor.pygments.filters import FILTERS out = [] for name, cls in FILTERS.items(): self.filenames.add(sys.modules[cls.__module__].__file__) docstring = cls.__doc__ if isinstance(docstring, bytes): docstring = docstring.decode('utf8') out.append(FILTERDOC % (cls.__name__, name, docstring)) return ''.join(out) def setup(app): app.add_directive('pygmentsdoc', PygmentsDoc)
Back to File Manager