markdown: Add extension for creating tabbed sections on /help and /api.

templates/zerver/tests/markdown/test_tabbed_sections.md

@@ -0,0 +1,22 @@
+# Heading
+
+{start_tabs}
+{tab|ios}
+iOS instructions
+
+{tab|desktop-web}
+
+Desktop/browser instructions
+
+{end_tabs}
+
+## Heading 2
+
+{start_tabs}
+
+{tab|desktop-web}
+
+Desktop/browser instructions
+{tab|android}
+Android instructions
+{end_tabs}

zerver/lib/bugdown/tabbed_sections.py

@@ -0,0 +1,118 @@
+import re
+
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+from typing import Any, Dict, Optional, List, Tuple
+import markdown
+
+START_TABBED_SECTION_REGEX = re.compile(r'^\{start_tabs\}$')
+END_TABBED_SECTION_REGEX = re.compile(r'^\{end_tabs\}$')
+TAB_CONTENT_REGEX = re.compile(r'^\{tab\|\s*(.+?)\s*\}$')
+
+CODE_SECTION_TEMPLATE = """
+<div class="code-section" markdown="1">
+{nav_bar}
+<div class="blocks">
+{blocks}
+</div>
+</div>
+""".strip()
+
+NAV_BAR_TEMPLATE = """
+<ul class="nav">
+{tabs}
+</ul>
+""".strip()
+
+NAV_LIST_ITEM_TEMPLATE = """
+<li data-language="{data_language}">{name}</li>
+""".strip()
+
+DIV_TAB_CONTENT_TEMPLATE = """
+<div data-language="{data_language}" markdown="1">
+{content}
+</div>
+""".strip()
+
+TAB_DISPLAY_NAMES = {
+    'desktop-web': 'Desktop/Web',
+    'ios': 'iOS',
+    'android': 'Android',
+}
+
+class TabbedSectionsGenerator(Extension):
+    def extendMarkdown(self, md: markdown.Markdown, md_globals: Dict[str, Any]) -> None:
+        md.preprocessors.add(
+            'tabbed_sections', TabbedSectionsPreprocessor(md, self.getConfigs()), '_end')
+
+class TabbedSectionsPreprocessor(Preprocessor):
+    def __init__(self, md: markdown.Markdown, config: Dict[str, Any]) -> None:
+        super(TabbedSectionsPreprocessor, self).__init__(md)
+
+    def run(self, lines: List[str]) -> List[str]:
+        tab_section = self.parse_tabs(lines)
+        while tab_section:
+            nav_bar = self.generate_nav_bar(tab_section)
+            content_blocks = self.generate_content_blocks(tab_section, lines)
+            rendered_tabs = CODE_SECTION_TEMPLATE.format(
+                nav_bar=nav_bar, blocks=content_blocks)
+
+            start = tab_section['start_tabs_index']
+            end = tab_section['end_tabs_index'] + 1
+            lines = lines[:start] + [rendered_tabs] + lines[end:]
+            tab_section = self.parse_tabs(lines)
+        return lines
+
+    def generate_content_blocks(self, tab_section: Dict[str, Any], lines: List[str]) -> str:
+        tab_content_blocks = []
+        for index, tab in enumerate(tab_section['tabs']):
+            start_index = tab['start'] + 1
+            try:
+                # If there are more tabs, we can use the starting index
+                # of the next tab as the ending index of the previous one
+                end_index = tab_section['tabs'][index + 1]['start']
+            except IndexError:
+                # Otherwise, just use the end of the entire section
+                end_index = tab_section['end_tabs_index']
+
+            content = '\n'.join(lines[start_index:end_index]).strip()
+            tab_content_block = DIV_TAB_CONTENT_TEMPLATE.format(
+                data_language=tab['tab_name'],
+                # Wrapping the content in two newlines is necessary here.
+                # If we don't do this, the inner Markdown does not get
+                # rendered properly.
+                content='\n{}\n'.format(content))
+            tab_content_blocks.append(tab_content_block)
+        return '\n'.join(tab_content_blocks)
+
+    def generate_nav_bar(self, tab_section: Dict[str, Any]) -> str:
+        li_elements = []
+        for tab in tab_section['tabs']:
+            li = NAV_LIST_ITEM_TEMPLATE.format(
+                data_language=tab.get('tab_name'),
+                name=TAB_DISPLAY_NAMES.get(tab.get('tab_name')))
+            li_elements.append(li)
+        return NAV_BAR_TEMPLATE.format(tabs='\n'.join(li_elements))
+
+    def parse_tabs(self, lines: List[str]) -> Optional[Dict[str, Any]]:
+        block = {}  # type: Dict[str, Any]
+        for index, line in enumerate(lines):
+            start_match = START_TABBED_SECTION_REGEX.search(line)
+            if start_match:
+                block['start_tabs_index'] = index
+
+            tab_content_match = TAB_CONTENT_REGEX.search(line)
+            if tab_content_match:
+                block.setdefault('tabs', [])
+                tab = {'start': index,
+                       'tab_name': tab_content_match.group(1)}
+                block['tabs'].append(tab)
+
+            end_match = END_TABBED_SECTION_REGEX.search(line)
+            if end_match:
+                block['end_tabs_index'] = index
+                break
+        return block
+
+def makeExtension(*args: Any, **kwargs: str) -> TabbedSectionsGenerator:
+    return TabbedSectionsGenerator(kwargs)

zerver/templatetags/app_filters.py

@@ -17,6 +17,7 @@ import zerver.lib.bugdown.fenced_code
 import zerver.lib.bugdown.api_arguments_table_generator
 import zerver.lib.bugdown.api_code_examples
 import zerver.lib.bugdown.nested_code_blocks
+import zerver.lib.bugdown.tabbed_sections
 import zerver.lib.bugdown.help_settings_links
 import zerver.lib.bugdown.help_relative_links
 import zerver.lib.bugdown.help_emoticon_translations_table
@@ -109,6 +110,7 @@ def render_markdown_path(markdown_file_path: str,
                 base_path='templates/zerver/api/'),
             zerver.lib.bugdown.api_code_examples.makeExtension(),
             zerver.lib.bugdown.nested_code_blocks.makeExtension(),
+            zerver.lib.bugdown.tabbed_sections.makeExtension(),
             zerver.lib.bugdown.help_settings_links.makeExtension(),
             zerver.lib.bugdown.help_relative_links.makeExtension(),
             zerver.lib.bugdown.help_emoticon_translations_table.makeExtension(),

zerver/tests/test_templates.py

@@ -218,6 +218,65 @@ class TemplateTestCase(ZulipTestCase):
         self.assertEqual(content_sans_whitespace,
                          'header<h1id="hello">Hello!</h1><p>Thisissome<em>boldtext</em>.</p>footer')
 
+    def test_markdown_tabbed_sections_extension(self) -> None:
+        template = get_template("tests/test_markdown.html")
+        context = {
+            'markdown_test_file': "zerver/tests/markdown/test_tabbed_sections.md"
+        }
+        content = template.render(context)
+        content_sans_whitespace = content.replace(" ", "").replace('\n', '')
+
+        # Note that the expected HTML has a lot of stray <p> tags. This is a
+        # consequence of how the Markdown renderer converts newlines to HTML
+        # and how elements are delimited by newlines and so forth. However,
+        # stray <p> tags are usually matched with closing tags by HTML renderers
+        # so this doesn't affect the final rendered UI in any visible way.
+        expected_html = """
+header
+
+<h1 id="heading">Heading</h1>
+<p>
+  <div class="code-section" markdown="1">
+    <ul class="nav">
+      <li data-language="ios">iOS</li>
+      <li data-language="desktop-web">Desktop/Web</li>
+    </ul>
+    <div class="blocks">
+      <div data-language="ios" markdown="1"></p>
+        <p>iOS instructions</p>
+      <p></div>
+      <div data-language="desktop-web" markdown="1"></p>
+        <p>Desktop/browser instructions</p>
+      <p></div>
+    </div>
+  </div>
+</p>
+
+<h2 id="heading-2">Heading 2</h2>
+<p>
+  <div class="code-section" markdown="1">
+    <ul class="nav">
+      <li data-language="desktop-web">Desktop/Web</li>
+      <li data-language="android">Android</li>
+    </ul>
+    <div class="blocks">
+      <div data-language="desktop-web" markdown="1"></p>
+        <p>Desktop/browser instructions</p>
+      <p></div>
+      <div data-language="android" markdown="1"></p>
+        <p>Android instructions</p>
+      <p></div>
+    </div>
+  </div>
+</p>
+
+footer
+"""
+
+        expected_html_sans_whitespace = expected_html.replace(" ", "").replace('\n', '')
+        self.assertEqual(content_sans_whitespace,
+                         expected_html_sans_whitespace)
+
     def test_encoded_unicode_decimals_in_markdown_template(self) -> None:
         template = get_template("tests/test_unicode_decimals.html")
         context = {'unescape_rendered_html': False}