DOP-2952: Literalinclude support for input/output directives (#398)

* DOP-2952: Literalinclude support for input directives

* add tests for full literalinclude functionality support

* add descriptors to rstspec.toml

Co-authored-by: Grace Chong <[email protected]>

Author: gjchong25

snooty/parser.py

@@ -727,85 +727,79 @@ def create_page() -> Tuple[Page, EmbeddedRstParser]:
             # Capture the original file-length before splicing it
             len_file = len(lines)
 
-            if name == "literalinclude":
-
-                def _locate_text(text: str) -> int:
-                    """
-                    Searches the literally-included file ('lines') for the specified text. If no such text is found,
-                    add an InvalidLiteralInclude diagnostic.
-                    """
-                    assert isinstance(text, str)
-                    loc = next(
-                        (idx for idx, line in enumerate(lines) if text in line), -1
+            def _locate_text(text: str) -> int:
+                """
+                Searches the literally-included file ('lines') for the specified text. If no such text is found,
+                add an InvalidLiteralInclude diagnostic.
+                """
+                assert isinstance(text, str)
+                loc = next((idx for idx, line in enumerate(lines) if text in line), -1)
+                if loc < 0:
+                    self.diagnostics.append(
+                        InvalidLiteralInclude(f'"{text}" not found in {filepath}', line)
                     )
-                    if loc < 0:
-                        self.diagnostics.append(
-                            InvalidLiteralInclude(
-                                f'"{text}" not found in {filepath}', line
-                            )
-                        )
-                    return loc
-
-                # Locate the start_after query
-                start_after = 0
-                if "start-after" in options:
-                    start_after_text = options["start-after"]
-                    # start_after = self._locate_text(start_after_text, lines, line, text)
-                    start_after = _locate_text(start_after_text)
-                    # Only increment start_after if text is specified, to avoid capturing the start_after_text
-                    start_after += 1
-
-                # ...now locate the end_before query
+                return loc
+
+            # Locate the start_after query
+            start_after = 0
+            if "start-after" in options:
+                start_after_text = options["start-after"]
+                # start_after = self._locate_text(start_after_text, lines, line, text)
+                start_after = _locate_text(start_after_text)
+                # Only increment start_after if text is specified, to avoid capturing the start_after_text
+                start_after += 1
+
+            # ...now locate the end_before query
+            end_before = len(lines)
+            if "end-before" in options:
+                end_before_text = options["end-before"]
+                # end_before = self._locate_text(end_before_text, lines, line, text)
+                end_before = _locate_text(end_before_text)
+
+            # Check that start_after_text precedes end_before_text (and end_before exists)
+            if start_after >= end_before >= 0:
+                self.diagnostics.append(
+                    InvalidLiteralInclude(
+                        f'"{end_before_text}" precedes "{start_after_text}" in {filepath}',
+                        line,
+                    )
+                )
+
+            # If we failed to locate end_before text, default to the end-of-file
+            if end_before == -1:
                 end_before = len(lines)
-                if "end-before" in options:
-                    end_before_text = options["end-before"]
-                    # end_before = self._locate_text(end_before_text, lines, line, text)
-                    end_before = _locate_text(end_before_text)
 
-                # Check that start_after_text precedes end_before_text (and end_before exists)
-                if start_after >= end_before >= 0:
+            lines = lines[start_after:end_before]
+
+            dedent = 0
+            if "dedent" in options:
+                # Dedent is specified as a flag
+                if isinstance(options["dedent"], bool):
+                    # Deduce a reasonable dedent
+                    try:
+                        dedent = min(
+                            len(line) - len(line.lstrip())
+                            for line in lines
+                            if len(line.lstrip()) > 0
+                        )
+                    except ValueError:
+                        # Handle the (unlikely) case where there are no non-empty lines
+                        dedent = 0
+                # Dedent is specified as a nonnegative integer (number of characters):
+                # Note: since boolean is a subtype of int, this conditonal must follow the
+                # above bool-type conditional.
+                elif isinstance(options["dedent"], int):
+                    dedent = options["dedent"]
+                else:
                     self.diagnostics.append(
                         InvalidLiteralInclude(
-                            f'"{end_before_text}" precedes "{start_after_text}" in {filepath}',
+                            f'Dedent "{dedent}" of type {type(dedent)}; expected nonnegative integer or flag',
                             line,
                         )
                     )
+                    return doc
 
-                # If we failed to locate end_before text, default to the end-of-file
-                if end_before == -1:
-                    end_before = len(lines)
-
-                lines = lines[start_after:end_before]
-
-                dedent = 0
-                if "dedent" in options:
-                    # Dedent is specified as a flag
-                    if isinstance(options["dedent"], bool):
-                        # Deduce a reasonable dedent
-                        try:
-                            dedent = min(
-                                len(line) - len(line.lstrip())
-                                for line in lines
-                                if len(line.lstrip()) > 0
-                            )
-                        except ValueError:
-                            # Handle the (unlikely) case where there are no non-empty lines
-                            dedent = 0
-                    # Dedent is specified as a nonnegative integer (number of characters):
-                    # Note: since boolean is a subtype of int, this conditonal must follow the
-                    # above bool-type conditional.
-                    elif isinstance(options["dedent"], int):
-                        dedent = options["dedent"]
-                    else:
-                        self.diagnostics.append(
-                            InvalidLiteralInclude(
-                                f'Dedent "{dedent}" of type {type(dedent)}; expected nonnegative integer or flag',
-                                line,
-                            )
-                        )
-                        return doc
-
-                lines = [line[dedent:] for line in lines]
+            lines = [line[dedent:] for line in lines]
 
             emphasize_lines = None
             if "emphasize-lines" in options:

snooty/rstspec.toml

@@ -499,10 +499,18 @@ help = """The code content."""
 argument_type = ["path", "raw"]
 content_type = "raw"
 options.language = "string"
+options.start-after = "string"
+options.end-before = "string"
+options.dedent = ["nonnegative_integer", "flag"]
+options.lineno-start = "nonnegative_integer"
 options.emphasize-lines = "linenos"
 options.linenos = "flag"
 example = """.. input:: ${0:code input or </path/to/file>}
       :language: ${1:language}
+      :start-after: ${2:text to start after (Optional}}
+      :end-before: ${3:text to end before (Optional}}
+      :dedent: ${4:number of chars to dedent by}
+      :lineno-start: ${5:nonnegative integer to start line numbering from}
       :emphasize-lines: (string)
       :linenos: (flag)
 """
@@ -512,11 +520,19 @@ help = """The code output."""
 argument_type = ["path", "raw"]
 content_type = "raw"
 options.language = "string"
+options.start-after = "string"
+options.end-before = "string"
+options.dedent = ["nonnegative_integer", "flag"]
+options.lineno-start = "nonnegative_integer"
 options.emphasize-lines = "linenos"
 options.linenos = "flag"
 options.visible = "boolean"
 example = """.. output:: ${0:code output or </path/to/file>}
       :language: ${1:language}
+      :start-after: ${2:text to start after (Optional}}
+      :end-before: ${3:text to end before (Optional}}
+      :dedent: ${4:number of chars to dedent by}
+      :lineno-start: ${5:nonnegative integer to start line numbering from}
       :emphasize-lines: (string)
       :linenos: (flag)
       :visible: (bool)

snooty/test_parser.py

@@ -654,6 +654,52 @@ def test_iocodeblock() -> None:
 </root>""",
     )
 
+    # Test full support of literalinclude options for input/output directives
+    page, diagnostics = parse_rst(
+        parser,
+        tabs_path,
+        """
+.. io-code-block::
+
+   .. input:: /test_parser/includes/sample_code.py
+      :language: python
+      :linenos:
+      :start-after: start example 1
+      :end-before: end example 2
+      :dedent: 4
+      :lineno-start: 2
+
+   .. output:: /test_parser/includes/sample_code.py
+      :language: python
+      :linenos:
+      :start-after: start example 2
+      :end-before: end example 2
+      :dedent: 4
+      :lineno-start: 6""",
+    )
+    page.finish(diagnostics)
+    assert diagnostics == []
+    check_ast_testing_string(
+        page.ast,
+        """
+<root fileid="test.rst">
+    <directive name="io-code-block">
+        <directive name="input" language="python" linenos="True" start-after="start example 1" end-before="end example 2" dedent="4" lineno-start="2">
+            <text>/test_parser/includes/sample_code.py</text>
+            <code lang="python" linenos="True" lineno_start="2">print("test dedent")
+# end example 1
+
+# start example 2
+print("hello world")
+            </code>
+        </directive>
+        <directive name="output" language="python" linenos="True" start-after="start example 2" end-before="end example 2" dedent="4" lineno-start="6">
+            <text>/test_parser/includes/sample_code.py</text><code lang="python" linenos="True" lineno_start="6">print("hello world")</code>
+       </directive>
+    </directive>
+</root>""",
+    )
+
     # Test a io-code-block with incorrect options linenos and emphasize-lines
     page, diagnostics = parse_rst(
         parser,