diff options
author | Matthäus G. Chajdas <dev@anteru.net> | 2022-10-24 21:54:24 +0200 |
---|---|---|
committer | Matthäus G. Chajdas <dev@anteru.net> | 2022-10-24 21:54:24 +0200 |
commit | e2aa606da2341e708b8e091e2c8338a62f9a41bf (patch) | |
tree | 9ff61f5043d07bdf333a02c49822a85d9dddb154 | |
parent | 5d521a619880723c8fafb9345a51e10c1d560948 (diff) | |
download | pygments-git-e2aa606da2341e708b8e091e2c8338a62f9a41bf.tar.gz |
Improve the languages list.
* Move the generation into sphinext, similar to other overviews we have.
* Generate a table instead of the plain list. This table contains links
to the lexer class now.
-rw-r--r-- | doc/_templates/languages.html | 31 | ||||
-rw-r--r-- | doc/conf.py | 12 | ||||
-rw-r--r-- | doc/languages.rst | 19 | ||||
-rw-r--r-- | pygments/sphinxext.py | 61 |
4 files changed, 77 insertions, 46 deletions
diff --git a/doc/_templates/languages.html b/doc/_templates/languages.html deleted file mode 100644 index e046a906..00000000 --- a/doc/_templates/languages.html +++ /dev/null @@ -1,31 +0,0 @@ -{% extends "layout.html" %} - -{% block htmltitle %}<title>Languages {{ titlesuffix }}</title>{% endblock %} - -{% block body %} - -<h1>Languages</h1> - -<ul> -{% for language in languages %} -<li> - {% if language.url %} - <a href="{{language.url}}">{{language.name}}</a> - {% else %} - {{language.name}} - {% endif %} -</li> -{% endfor %} -</ul> -{{ body }} - -<h1>... that's all?</h1> - -Well, why not write your own? Contributing to Pygments is easy and fun. Take a -look at the <a href="{{ pathto('docs/lexerdevelopment') }}">docs on lexer development</a>. Pull -requests are welcome on <a href="https://github.com/pygments/pygments">GitHub</a>. - -Note: the languages listed here are supported in the development version. The -latest release may lack a few of them. - -{% endblock %} diff --git a/doc/conf.py b/doc/conf.py index 0023585d..f42c3553 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -134,7 +134,6 @@ html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']} # template names. html_additional_pages = { 'styles': 'styles.html', - 'languages': 'languages.html' } if os.environ.get('WEBSITE_BUILD'): @@ -233,17 +232,8 @@ rst_prolog = '.. |language_count| replace:: {}'.format(len(list(pygments.lexers. def pg_context(app, pagename, templatename, ctx, event_arg): ctx['demo_active'] = bool(os.environ.get('WEBSITE_BUILD')) - if pagename in ('demo', 'languages'): - all_lexers = sorted(pygments.lexers.get_all_lexers(plugins=False), key=lambda x: x[0].lower()) if pagename == 'demo': - ctx['lexers'] = all_lexers - - if pagename == 'languages': - lexer_name_url = [] - for entry in all_lexers: - lexer_cls = pygments.lexers.find_lexer_class(entry[0]) - lexer_name_url.append({'name': entry[0], 'url': lexer_cls.url}) - ctx['languages'] = lexer_name_url + ctx['lexers'] = sorted(pygments.lexers.get_all_lexers(plugins=False), key=lambda x: x[0].lower()) if pagename in ('styles', 'demo'): with open('examples/example.py') as f: diff --git a/doc/languages.rst b/doc/languages.rst index a39b94f1..2e9f1ff3 100644 --- a/doc/languages.rst +++ b/doc/languages.rst @@ -1,5 +1,16 @@ -:orphan: +Languages +========= -This file is overridden by _templates/languages.html and just exists to -allow the language list to be reliably linked from the documentation -(since its location varies between `make html` and `make dirhtml`). +.. pygmentsdoc:: lexers_overview + +... that's all? +--------------- + +Well, why not write your own? Contributing to Pygments is easy and fun. Take a +look at the :doc:`docs on lexer development <lexerdevelopment>`. Pull +requests are welcome on <a href="https://github.com/pygments/pygments">GitHub</a>. + +.. note:: + + The languages listed here are supported in the development version. The + latest release may lack a few of them. diff --git a/pygments/sphinxext.py b/pygments/sphinxext.py index f1405eb8..aa05bed1 100644 --- a/pygments/sphinxext.py +++ b/pygments/sphinxext.py @@ -74,6 +74,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,6 +85,65 @@ 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"), and a link to the lexer class.""" + from pygments.lexers._mapping import LEXERS + import pygments.lexers + 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 = pygments.lexers.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 l, c in zip(column_lengths, columns): + if c: + out.append(c.ljust(l)) + else: + out.append(' '*l) + + 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', 'Extensions', 'Aliases', '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 pygments.lexers._mapping import LEXERS out = [] |