Merge pull request #2260 from pygments/improve-languages-list

Improve the languages list.

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..1bc49543 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"), the aliases 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', '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 pygments.lexers._mapping import LEXERS
         out = []