don't break back-compatibility

docs/syntax/roles-and-directives.md

@@ -74,7 +74,7 @@ print(f'my {a}nd line')
 :::
 
 Comments, starting `#`, are also allowed in between options or at the end of values, and are ignored.
-The values can be enclosed in quotes and span multiple lines.
+The values can be enclosed in quotes (`"` or `'`) and span multiple lines.
 Newline behaviour can be controlled by starting the value with `|` (preserve newlines) or `>` (collapse newlines):
 
 :::{myst-example}

myst_parser/mdit_to_docutils/base.py

@@ -1752,7 +1752,7 @@ def run_directive(
             self.create_warning(
                 f"{name!r}: {warning_msg}",
                 MystWarnings.DIRECTIVE_PARSING,
-                line=warning_line,
+                line=warning_line if warning_line is not None else position,
                 append_to=self.current_node,
             )
 

myst_parser/mocking.py

@@ -140,7 +140,7 @@ def parse_directive_block(
         if option_presets:
             raise MockingError("parse_directive_block: option_presets not implemented")
         # TODO should argument_str always be ""?
-        parsed = parse_directive_text(directive, "", "\n".join(content), self._lineno)
+        parsed = parse_directive_text(directive, "", "\n".join(content))
         if parsed.warnings:
             raise MarkupError(",".join(w for w, _ in parsed.warnings))
         return (

myst_parser/parsers/directives.py

@@ -60,7 +60,7 @@ class DirectiveParsingResult:
     """The lines of body content"""
     body_offset: int
     """The number of lines to the start of the body content."""
-    warnings: list[tuple[str, int]]
+    warnings: list[tuple[str, int | None]]
     """List of non-fatal errors encountered during parsing.
     (message, line_number)
     """
@@ -70,8 +70,8 @@ def parse_directive_text(
     directive_class: type[Directive],
     first_line: str,
     content: str,
-    line: int,
     *,
+    line: int | None = None,
     validate_options: bool = True,
     additional_options: dict[str, str] | None = None,
 ) -> DirectiveParsingResult:
@@ -88,14 +88,14 @@ def parse_directive_text(
 
     :raises MarkupError: if there is a fatal parsing/validation error
     """
-    parse_errors: list[tuple[str, int]] = []
+    parse_errors: list[tuple[str, int | None]] = []
     options: dict[str, Any] = {}
     body_lines = content.splitlines()
     content_offset = 0
 
     if directive_class.option_spec:
         # only look for an option block if there are possible options
-        body, options, option_errors = _parse_directive_options(
+        body, options, option_errors = parse_directive_options(
             content,
             directive_class,
             line=line,
@@ -122,27 +122,27 @@ def parse_directive_text(
 
     # check for body content
     if body_lines and not directive_class.has_content:
-        parse_errors.append(("Has content, but none permitted", line + content_offset))
+        parse_errors.append(("Has content, but none permitted", None))
 
     return DirectiveParsingResult(
         arguments, options, body_lines, content_offset, parse_errors
     )
 
 
-def _parse_directive_options(
+def parse_directive_options(
     content: str,
     directive_class: type[Directive],
     as_yaml: bool,
-    line: int,
+    line: int | None,
     additional_options: dict[str, str] | None = None,
-) -> tuple[str, dict, list[tuple[str, int]]]:
+) -> tuple[str, dict, list[tuple[str, int | None]]]:
     """Parse (and validate) the directive option section.
 
     :returns: (content, options, validation_errors)
     """
     yaml_block: None | str = None
     if content.startswith("---"):
-        line += 1
+        line = None if line is None else line + 1
         content = "\n".join(content.splitlines()[1:])
         match = re.search(r"^-{3,}", content, re.MULTILINE)
         if match:
@@ -163,7 +163,7 @@ def _parse_directive_options(
         content = "\n".join(content_lines)
 
     if as_yaml:
-        yaml_errors: list[tuple[str, int]] = []
+        yaml_errors: list[tuple[str, int | None]] = []
         try:
             yaml_options = yaml.safe_load(yaml_block or "") or {}
         except (yaml.parser.ParserError, yaml.scanner.ScannerError):
@@ -194,7 +194,7 @@ def _parse_directive_options(
     options_spec: dict[str, Callable] = directive_class.option_spec
     unknown_options: list[str] = []
     new_options: dict[str, Any] = {}
-    validation_errors: list[tuple[str, int]] = []
+    validation_errors: list[tuple[str, int | None]] = []
     value: str | None
     for name, value in options.items():
         try:

tests/test_renderers/test_parse_directives.py

@@ -49,7 +49,7 @@ def test_parsing(file_params):
         raise AssertionError(f"Unknown directive: {name}")
     try:
         result = parse_directive_text(
-            klass, first_line[0] if first_line else "", tokens[0].content, 0
+            klass, first_line[0] if first_line else "", tokens[0].content, line=0
         )
     except MarkupError as err:
         outcome = f"error: {err}"
@@ -72,12 +72,12 @@ def test_parsing(file_params):
 )
 def test_parsing_errors(descript, klass, arguments, content):
     with pytest.raises(MarkupError):
-        parse_directive_text(klass, arguments, content, 0)
+        parse_directive_text(klass, arguments, content)
 
 
 def test_parsing_full_yaml():
     result = parse_directive_text(
-        Note, "", "---\na: [1]\n---\ncontent", 0, validate_options=False
+        Note, "", "---\na: [1]\n---\ncontent", validate_options=False
     )
     assert not result.warnings
     assert result.options == {"a": [1]}
@@ -88,28 +88,28 @@ def test_additional_options():
     """Allow additional options to be passed to a directive."""
     # this should be fine
     result = parse_directive_text(
-        Note, "", "content", 0, additional_options={"class": "bar"}
+        Note, "", "content", additional_options={"class": "bar"}
     )
     assert not result.warnings
     assert result.options == {"class": ["bar"]}
     assert result.body == ["content"]
     # body on first line should also be fine
     result = parse_directive_text(
-        Note, "content", "other", 0, additional_options={"class": "bar"}
+        Note, "content", "other", additional_options={"class": "bar"}
     )
     assert not result.warnings
     assert result.options == {"class": ["bar"]}
     assert result.body == ["content", "other"]
     # additional option should not take precedence
     result = parse_directive_text(
-        Note, "content", ":class: foo", 0, additional_options={"class": "bar"}
+        Note, "content", ":class: foo", additional_options={"class": "bar"}
     )
     assert not result.warnings
     assert result.options == {"class": ["foo"]}
     assert result.body == ["content"]
     # this should warn about the unknown option
     result = parse_directive_text(
-        Note, "", "content", 0, additional_options={"foo": "bar"}
+        Note, "", "content", additional_options={"foo": "bar"}
     )
     assert len(result.warnings) == 1
     assert "Unknown option" in result.warnings[0][0]