Implement warning block, rework follower (back to previous state),

improve test coverage

Author: krassowski

docstring_to_markdown/rst.py

@@ -110,26 +110,31 @@ class IParser(ABC):
 
     @abstractmethod
     def can_parse(self, line: str) -> bool:
-        pass
+        """Whether the line looks like a valid beginning of parsed block."""
 
     @abstractmethod
     def initiate_parsing(self, line: str, current_language: str) -> IBlockBeginning:
-        pass
+        """Initiate parsing of given line.
+
+        Arguments:
+            line: first line to be parsed (that passed `can_parse()` test)
+            current_language: language to use if highlighting code and no other language is specified in `line`
+        """
 
     @abstractmethod
     def can_consume(self, line: str) -> bool:
-        pass
+        """Whether the line can be parsed, or does it look like an end of parsable area?"""
 
     @abstractmethod
     def consume(self, line: str) -> None:
-        pass
+        """Parse given line."""
 
     @abstractmethod
     def finish_consumption(self, final: bool) -> str:
-        pass
+        """Finish parsing and return the converted part of the docstring."""
 
-    def get_follower(self, line: str) -> Union['IParser', None]:
-        return None
+    """Is there another parser that should follow after this parser finished?"""
+    follower: Union['IParser', None] = None
 
 
 class BlockParser(IParser):
@@ -144,27 +149,12 @@ def __init__(self):
 
     @abstractmethod
     def can_parse(self, line: str) -> bool:
-        """
-        All children should call _start_block in initiate_parsing() implementation.
-        """
-        pass
-
-    @abstractmethod
-    def initiate_parsing(
-            self,
-            line: str,
-            current_language: str
-    ) -> IBlockBeginning:
-        pass
+        """All children should call _start_block in initiate_parsing() implementation."""
 
     def _start_block(self, language: str):
         self._buffer.append(self.enclosure + language)
         self._block_started = True
 
-    @abstractmethod
-    def can_consume(self, line: str) -> bool:
-        pass
-
     def consume(self, line: str):
         if not self._block_started:
             raise ValueError('Block has not started')
@@ -222,8 +212,7 @@ def can_consume(self, line: str) -> bool:
         return line.strip() != '' and not line.startswith('>>>')
 
     def can_parse(self, line: str) -> bool:
-        # cannot be initiated directly
-        return False
+        return line.strip() != ''
 
     def initiate_parsing(self, line: str, current_language: str) -> IBlockBeginning:
         self._start_block('')
@@ -250,9 +239,7 @@ def _strip_prompt(self, line: str) -> str:
         start = 4 if line.startswith('>>> ') or line.startswith('... ') else 3
         return line[start:]
 
-    def get_follower(self, line: str) -> Union['IParser', None]:
-        if line:
-            return PythonOutputBlockParser()
+    follower = PythonOutputBlockParser()
 
 
 class DoubleColonBlockParser(IndentedBlockParser):
@@ -286,12 +273,13 @@ def initiate_parsing(self, line: str, current_language: str):
 
 class NoteBlockParser(IndentedBlockParser):
     enclosure = '\n---'
+    directives = {'.. note::', '.. warning::'}
 
     def can_parse(self, line: str):
-        return line.strip() == '.. note::'
+        return line.strip() in self.directives
 
     def initiate_parsing(self, line: str, current_language: str):
-        self._start_block('\n**Note**\n')
+        self._start_block('\n**Note**\n' if 'note' in line else '\n**Warning**\n')
         return IBlockBeginning(remainder='')
 
 
@@ -378,8 +366,8 @@ def flush_buffer():
             else:
                 markdown += flush_buffer()
                 markdown += active_parser.finish_consumption(False)
-                follower = active_parser.get_follower(line)
-                if follower:
+                follower = active_parser.follower
+                if follower and follower.can_parse(line):
                     active_parser = follower
                     active_parser.initiate_parsing(line, language)
                 else:

setup.cfg

@@ -27,7 +27,7 @@ python_requires = >=3.6
 addopts =
     --pyargs tests
     --cov docstring_to_markdown
-    --cov-fail-under=92
+    --cov-fail-under=97
     --cov-report term-missing:skip-covered
     -p no:warnings
     --flake8

tests/test_rst.py

@@ -350,6 +350,32 @@ def func(): pass
 
 """
 
+WARNING_BLOCK = """
+Load pickled object from file.
+
+.. warning::
+   Loading pickled data received from untrusted sources can be
+   unsafe.
+
+Parameters
+"""
+
+
+WARNING_BLOCK_MARKDOWN = """
+Load pickled object from file.
+
+
+---
+**Warning**
+
+Loading pickled data received from untrusted sources can be
+unsafe.
+
+---
+
+Parameters
+"""
+
 
 INTEGRATION = """
 Return a fixed frequency DatetimeIndex.
@@ -431,6 +457,10 @@ def func(): pass
     'separates following paragraph after a code blocks without output': {
         'rst': CODE_BLOCK_BUT_NOT_OUTPUT,
         'md': CODE_BLOCK_BUT_NOT_OUTPUT_MD
+    },
+    'converts warnings': {
+        'rst': WARNING_BLOCK,
+        'md': WARNING_BLOCK_MARKDOWN
     }
 }
 
@@ -440,6 +470,7 @@ def test_looks_like_rst_recognises_rst():
     assert looks_like_rst('the following code ::\n\n\tcode')
     assert looks_like_rst('the following code::\n\n\tcode')
     assert looks_like_rst('See Also\n--------\n')
+    assert looks_like_rst('.. versionadded:: 0.1')
 
 
 def test_looks_like_rst_ignores_plain_text():