Merge pull request #20 from krassowski/full-admonition-support

Complete support for RST admonitions

Author: krassowski

docstring_to_markdown/rst.py

@@ -156,6 +156,75 @@ def __init__(
 ]
 
 
+class Admonition:
+    def __init__(self, name: str, label: str, icon: str = ''):
+        self.name = name
+        self.label = label
+        self.icon = icon
+
+    @property
+    def block_markdown(self):
+        return f'{self.icon} **{self.label}**'
+
+    @property
+    def inline_markdown(self):
+        return self.block_markdown + ':'
+
+
+ADMONITIONS = [
+    Admonition(
+        name='caution',
+        label='Caution',
+        icon='⚠️ '
+    ),
+    Admonition(
+        name='attention',
+        label='Attention',
+        icon='⚠️ '
+    ),
+    Admonition(
+        name='danger',
+        label='Danger',
+        icon='⚠️ '
+    ),
+    Admonition(
+        name='hint',
+        label='Hint',
+        icon='🛈'
+    ),
+    Admonition(
+        name='important',
+        label='Important',
+        icon='⚠️ '
+    ),
+    Admonition(
+        name='note',
+        label='Note',
+        icon='🛈'
+    ),
+    Admonition(
+        name='tip',
+        label='Tip',
+        icon='🛈'
+    ),
+    Admonition(
+        name='warning',
+        label='Warning',
+        icon='⚠️ '
+    )
+]
+
+
+ADMONITION_DIRECTIVES: List[Directive] = [
+    # https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
+    Directive(
+        pattern=rf'\.\. {admonition.name}::',
+        replacement=admonition.inline_markdown
+    )
+    for admonition in ADMONITIONS
+]
+
+
 RST_DIRECTIVES: List[Directive] = [
     Directive(
         pattern=r'\.\. versionchanged:: (?P<version>\S+)(?P<end>$|\n)',
@@ -169,10 +238,7 @@ def __init__(
         pattern=r'\.\. deprecated:: (?P<version>\S+)(?P<end>$|\n)',
         replacement=r'*Deprecated since \g<version>*\g<end>'
     ),
-    Directive(
-        pattern=r'\.\. warning::',
-        replacement=r'**Warning**:'
-    ),
+    *ADMONITION_DIRECTIVES,
     Directive(
         pattern=r'\.\. seealso::(?P<short_form>.*)(?P<end>$|\n)',
         replacement=r'*See also*\g<short_form>\g<end>'
@@ -605,13 +671,17 @@ def initiate_parsing(self, line: str, current_language: str):
 
 class NoteBlockParser(IndentedBlockParser):
     enclosure = '\n---'
-    directives = {'.. note::', '.. warning::'}
+    directives = {
+        f'.. {admonition.name}::': admonition
+        for admonition in ADMONITIONS
+    }
 
     def can_parse(self, line: str):
         return line.strip() in self.directives
 
     def initiate_parsing(self, line: str, current_language: str):
-        self._start_block('\n**Note**\n' if 'note' in line else '\n**Warning**\n')
+        admonition = self.directives[line.strip()]
+        self._start_block(f'\n{admonition.block_markdown}\n')
         return IBlockBeginning(remainder='')
 
 

tests/test_rst.py

@@ -243,7 +243,7 @@ def func(): pass
 
 
 ---
-**Note**
+🛈 **Note**
 
 The `chararray` class exists for backwards compatibility with
 Numarray, it is not recommended for new development.
@@ -399,7 +399,7 @@ def func(): pass
 
 
 ---
-**Warning**
+⚠️  **Warning**
 
 Loading pickled data received from untrusted sources can be
 unsafe.
@@ -421,7 +421,7 @@ def func(): pass
 LINE_WARNING_MARKDOWN = """
 Create a view into the array with the given shape and strides.
 
-**Warning**: This function has to be used with extreme care, see notes.
+⚠️  **Warning**: This function has to be used with extreme care, see notes.
 
 Parameters
 """
@@ -462,7 +462,7 @@ def func(): pass
 """
 
 SIMPLE_TABLE_MARKDOWN = """
-**Warning**: This is not a standard simple table
+⚠️  **Warning**: This is not a standard simple table
 
 | Character |                             Meaning                             |
 | --------- | --------------------------------------------------------------- |
@@ -501,7 +501,7 @@ def func(): pass
 """
 
 SIMPLE_TABLE_2_MARKDOWN = """
-**Warning**: This is a standard simple table
+⚠️  **Warning**: This is a standard simple table
 
 |   A   |   B   | A and B |
 | ----- | ----- | ------- |