robotcode-robot 2.9.0.dev115__tar.gz → 2.9.0.dev124__tar.gz

{robotcode_robot-2.9.0.dev115 → robotcode_robot-2.9.0.dev124}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: robotcode-robot
-Version: 2.9.0-dev.115
+Version: 2.9.0-dev.124
 Summary: Support classes for RobotCode for handling Robot Framework projects.
 Project-URL: Homepage, https://robotcode.io
 Project-URL: Donate, https://opencollective.com/robotcode
@@ -27,7 +27,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: platformdirs>=4.3
-Requires-Dist: robotcode-core==2.9.0-dev.115
+Requires-Dist: robotcode-core==2.9.0-dev.124
 Requires-Dist: robotframework>=5.0.0
 Requires-Dist: tomli>=1.1.0; python_version < '3.11'
 Description-Content-Type: text/markdown

{robotcode_robot-2.9.0.dev115 → robotcode_robot-2.9.0.dev124}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
   "robotframework>=5.0.0",
   "tomli>=1.1.0; python_version < '3.11'",
   "platformdirs>=4.3",
-  "robotcode-core==2.9.0-dev.115",
+  "robotcode-core==2.9.0-dev.124",
 ]
 dynamic = ["version"]
 

robotcode_robot-2.9.0.dev124/src/robotcode/robot/__version__.py

@@ -0,0 +1 @@
+__version__ = "2.9.0-dev.124"

{robotcode_robot-2.9.0.dev115 → robotcode_robot-2.9.0.dev124}/src/robotcode/robot/diagnostics/library_doc.py

@@ -90,6 +90,7 @@ from ..utils.markdown_docs import (
     code_span,
     code_span_variables,
     escape_link_text,
+    escape_text,
     extract_reference_definitions,
     heading_anchors,
     iter_headings,
@@ -99,6 +100,7 @@ from ..utils.markdown_docs import (
     section_anchors,
     shift_headings,
     slugify,
+    unescape_text,
     unique_reference_labels,
 )
 from ..utils.markdownformatter import MarkDownFormatter, NameLinker
@@ -241,18 +243,17 @@ def _page_heading_shift(doc_format: str, levels: int) -> Optional[Callable[[str]
 
 
 # A run of `#` after a space at the end of a keyword name would close its ATX heading: `### Use C #` shows "Use C".
-_RE_CLOSING_HASHES = re.compile(r"(\s)(#+)$")
-_RE_ESCAPED_CLOSING_HASHES = re.compile(r"(\s)\\(#+)$")
 
 
 def _heading_name(name: str) -> str:
-    """A keyword name as the title of its heading: a closing run of `#` escaped."""
-    return _RE_CLOSING_HASHES.sub(r"\1\\\2", name)
+    """A keyword name as the title of its heading: what Markdown would read as markup escaped,
+    also a closing run of `#`."""
+    return escape_text(name)
 
 
 def _heading_title_name(title: str) -> str:
     """The keyword name of a heading title that `_heading_name` wrote."""
-    return _RE_ESCAPED_CLOSING_HASHES.sub(r"\1\2", title)
+    return unescape_text(title)
 
 
 def _match_heading_anchors(headings: List[Tuple[str, str]], titles: List[Set[str]]) -> List[str]:
@@ -1348,7 +1349,8 @@ class KeywordDoc(SourceEntity):
         if add_type:
             result = (
                 f"#{'#' * header_level} "
-                f"{(self.libtype or 'Library').capitalize() if self.is_initializer else 'Keyword'} *{self.name}*\n"
+                f"{(self.libtype or 'Library').capitalize() if self.is_initializer else 'Keyword'} "
+                f"*{_heading_name(self.name)}*\n"
             )
         else:
             if not self.is_initializer:
@@ -1993,9 +1995,9 @@ class LibraryDoc:
         for level, title, anchor in heading_anchors(page):
             if level == header_level + 2:
                 in_introduction = title == "Introduction"
-                section_anchors_by_title.setdefault(normalize_reference(title), anchor)
+                section_anchors_by_title.setdefault(normalize_reference(_heading_title_name(title)), anchor)
             elif level > header_level + 2 and in_introduction:
-                introduction.setdefault(normalize_reference(title), anchor)
+                introduction.setdefault(normalize_reference(_heading_title_name(title)), anchor)
         section_anchors_by_title.update(introduction)
         _, type_anchors = self.get_page_anchors(page, header_level)
 

{robotcode_robot-2.9.0.dev115 → robotcode_robot-2.9.0.dev124}/src/robotcode/robot/utils/markdown_docs.py

@@ -22,6 +22,7 @@ __all__ = [
     "code_span",
     "code_span_variables",
     "escape_link_text",
+    "escape_text",
     "extract_reference_definitions",
     "heading_anchors",
     "iter_headings",
@@ -35,6 +36,7 @@ __all__ = [
     "section_anchors",
     "shift_headings",
     "slugify",
+    "unescape_text",
     "unique_reference_labels",
 ]
 
@@ -148,6 +150,36 @@ def escape_link_text(text: str) -> str:
     return _RE_LINK_TEXT_SPECIAL.sub(r"\\\1", text)
 
 
+_RE_TEXT_SPECIAL = re.compile(
+    r"""
+  \\(?=[!-/:-@\[-`{-~]|\Z)     # a backslash before ASCII punctuation or at the end
+| [<\#`]                       # always
+| (?<!\s)\* | \*(?!\s)         # a star, unless it has space on both sides
+| (?<![^\W_])_ | _(?![^\W_])   # an underscore, unless it is inside a word
+| &(?=\#?\w+;)                 # what reads as an entity
+| \](?=\()                     # what reads as an inline link
+| ~(?=~) | (?<=~)~             # what reads as strikethrough
+""",
+    re.VERBOSE,
+)
+_RE_ESCAPED_VARIABLE = re.compile(r"(?<!\\)((?:\\\\)+)\$")
+_RE_MARKDOWN_ESCAPE = re.compile(r"\\([!-/:-@\[-`{-~])")
+
+
+def escape_text(text: str) -> str:
+    """Escape what Markdown would read as markup in text that is meant as text, only where
+    it would change the text: `snake_case`, `${list}[0]` and `2 * 3` stay as they are.
+
+    An odd number of backslashes before `$` is an escaped variable and stays one."""
+    text = _RE_TEXT_SPECIAL.sub(r"\\\g<0>", text)
+    return _RE_ESCAPED_VARIABLE.sub(lambda m: m.group(1) + ("\\$" if len(m.group(1)) % 4 else "$"), text)
+
+
+def unescape_text(text: str) -> str:
+    """The text that Markdown shows for `text`, without its escapes."""
+    return _RE_MARKDOWN_ESCAPE.sub(r"\1", text)
+
+
 def anchor_link_resolver(kind: str, name: str) -> Optional[str]:
     """A `LinkResolver` for pages that show a whole library: keywords and
     sections have a heading there. The heading of a type can carry a number,
@@ -555,7 +587,8 @@ def _code_span_variables_in(text: str) -> str:
         # variables that follow each other directly share one code span: `${TEMPDIR}${/}`
         while (following := search_variable(text[end:], "$", ignore_errors=True)).start == 0:
             end += following.end
-        result.append(text[: match.start] + code_span(text[match.start : end]))
+        # inside code an escape would show
+        result.append(text[: match.start] + code_span(unescape_text(text[match.start : end])))
         text = text[end:]
     result.append(text)
     return "".join(result)

{robotcode_robot-2.9.0.dev115 → robotcode_robot-2.9.0.dev124}/src/robotcode/robot/utils/markdownformatter.py

@@ -5,7 +5,7 @@ import re
 from abc import ABC, abstractmethod
 from typing import Any, Callable, Final, Iterator, List, Optional, Tuple
 
-from .markdown_docs import code_span, escape_link_text
+from .markdown_docs import code_span, escape_link_text, escape_text
 
 # Gets a name in single backticks of documentation in Robot Framework's format and
 # returns the target of a link to it, or `None` if it stays inline code.
@@ -19,10 +19,15 @@ _RE_CODE_SPAN: Final["re.Pattern[str]"] = re.compile(
 | (?<!`) (`+) (?!`)      # a run of backticks (group 1)
   ([^\ue000]+?)          # anything but code that is already held (group 2)
   (?<!`) \1 (?!`)        # up to the next run of the same length
-| `+                     # a run of backticks without a partner
 """,
     re.VERBOSE,
 )
+# the documentation's own characters that the conversion uses
+_RE_OWN_MARKERS: Final["re.Pattern[str]"] = re.compile("[\ue000\ue002\ue003]")
+# what is no text: held code (group 1) and the syntax the formatter writes itself (group 2)
+_RE_NOT_TEXT: Final["re.Pattern[str]"] = re.compile("(\ue000\\d+\ue001)|\ue002(.*?)\ue003")
+# what starts a Markdown block: a quote, a list or a reference definition (group 1), a numbered list (groups 2 and 3)
+_RE_BLOCK_START: Final["re.Pattern[str]"] = re.compile(r"^(?:(>|[+-](?=\s|$)|\[(?=[^\]]*\]:))|(\d{1,9})([.)])(?=\s|$))")
 _RE_THREE_BACKTICKS: Final["re.Pattern[str]"] = re.compile("(?<!`)```(?!`)")
 _RE_LONG_BACKTICKS: Final["re.Pattern[str]"] = re.compile("`{3,}")
 
@@ -123,7 +128,7 @@ class HeaderFormatter(SingleLineFormatter):
         if m is not None:
             level, text = m.groups()
 
-            return "%s %s\n" % ("#" * (len(level) + 1), text)
+            return "%s %s\n" % ("#" * (len(level) + 1), _format_heading(text))
         return ""
 
 
@@ -155,15 +160,14 @@ class LinkFormatter:
         return pre + self._get_link(url)
 
     def _get_image(self, src: str, title: Optional[str] = None) -> str:
-        return f"![{title or src}]({self._target(src)})"
+        return _syntax(f"![{escape_text(title or src)}]({self._target(src)})")
 
     def _get_link(self, href: str, content: Optional[str] = None) -> str:
-        return f"[{content or href}]({self._target(href)})"
+        return _syntax("[") + (content or href) + _syntax(f"]({self._target(href)})")
 
     def _target(self, target: str) -> str:
-        # `#` is escaped in the whole line before links are formatted, a link target needs it as it is
-        target = target.replace("\\#", "#")
-        # Markdown takes a target with spaces only in angle brackets; `<` is already escaped in the whole line
+        target = target.replace("<", "\\<")
+        # Markdown takes a target with spaces only in angle brackets
         if " " in target:
             return "<" + target.replace(">", "\\>") + ">"
         return target
@@ -184,7 +188,7 @@ class LinkFormatter:
             content = self._get_image(content, link)
         elif self._is_image(link):
             return self._get_image(link, content)
-        if link.startswith("\\#"):
+        if link.startswith("#"):
             link = link.lower()
         return self._get_link(link, content)
 
@@ -214,6 +218,46 @@ def _hold(held: List[str], text: str) -> str:
     return f"\ue000{len(held) - 1}\ue001"
 
 
+def _hold_own_markers(line: str, held: List[str]) -> str:
+    return _RE_OWN_MARKERS.sub(lambda m: _hold(held, m.group(0)), line)
+
+
+def _restore(line: str, held: List[str]) -> str:
+    # backwards, the documentation's own characters can be part of held code
+    for index, text in reversed(list(enumerate(held))):
+        line = line.replace(f"\ue000{index}\ue001", text)
+    return line
+
+
+def _syntax(text: str) -> str:
+    """Marks what the formatter writes itself, the escape of the text leaves it alone."""
+    return f"\ue002{text}\ue003"
+
+
+def _escape_line(line: str) -> str:
+    result: List[str] = []
+    position = 0
+    for match in _RE_NOT_TEXT.finditer(line):
+        result.append(escape_text(line[position : match.start()]))
+        result.append(match.group(1) or match.group(2))
+        position = match.end()
+    result.append(escape_text(line[position:]))
+    return "".join(result)
+
+
+def _escape_block_start(match: re.Match[str]) -> str:
+    return f"\\{match.group(1)}" if match.group(1) else f"{match.group(2)}\\{match.group(3)}"
+
+
+def _format_heading(text: str) -> str:
+    """Robot Framework formats nothing in a heading, what Markdown would read as markup is text there."""
+    held: List[str] = []
+    text = _hold_own_markers(text, held)
+    if "`" in text:
+        text = _RE_CODE_SPAN.sub(lambda m: m.group(0) if m.group(1) is None else _hold(held, m.group(0)), text)
+    return _restore(_escape_line(text), held)
+
+
 class LineFormatter:
     _bold: Final["re.Pattern[str]"] = re.compile(
         r"""
@@ -257,8 +301,6 @@ _                          # end of italic
 
         self._name_linker = name_linker
         self._formatters: List[Tuple[str, Callable[[str], str]]] = [
-            ("<", self._quote_lower_then),
-            ("#", self._quote_hash),
             ("*", self._format_bold),
             ("_", self._format_italic),
             ("", LinkFormatter().format_link),
@@ -266,9 +308,7 @@ _                          # end of italic
 
     def format(self, line: str) -> str:
         held: List[str] = []
-        if "\ue000" in line:
-            # the documentation's own character must not read as a placeholder
-            line = line.replace("\ue000", _hold(held, "\ue000"))
+        line = _hold_own_markers(line, held)
         if "`" in line:
             # what Robot Framework reads as code decides first, then what else Markdown reads as code
             line = self._code.sub(lambda m: m.group(1) + _hold(held, code_span(_code_text(m.group(3)))), line)
@@ -276,16 +316,14 @@ _                          # end of italic
         for marker, formatter in self._formatters:
             if marker in line:
                 line = formatter(line)
-        # backwards, the documentation's own character can be part of held code
-        for index, text in reversed(list(enumerate(held))):
-            line = line.replace(f"\ue000{index}\ue001", text)
-        return line
+        # last, so that all that is left of the line is text
+        line = _RE_BLOCK_START.sub(_escape_block_start, _escape_line(line))
+        return _restore(line, held)
 
     def _hold_span(self, match: re.Match[str], held: List[str]) -> str:
         text, fence, span = match.group(0, 1, 2)
         if fence is None:
-            # Markdown must not pair a backtick left over with the code written here
-            return text if text.startswith("\\") else text.replace("`", "\\`")
+            return text
         # for Robot Framework this is no code, but Markdown shows it as code
         if len(fence) > 1:
             return _hold(held, text)
@@ -294,17 +332,11 @@ _                          # end of italic
             return _hold(held, f"[{escape_link_text(span)}]({target})")
         return _hold(held, code_span(_code_text(span)))
 
-    def _quote_lower_then(self, line: str) -> str:
-        return line.replace("<", "\\<")
-
-    def _quote_hash(self, line: str) -> str:
-        return line.replace("#", "\\#")
-
     def _format_bold(self, line: str) -> str:
-        return self._bold.sub("\\1**\\3**", line)
+        return self._bold.sub(f"\\1{_syntax('**')}\\3{_syntax('**')}", line)
 
     def _format_italic(self, line: str) -> str:
-        return self._italic.sub("\\1*\\3*", line)
+        return self._italic.sub(f"\\1{_syntax('*')}\\3{_syntax('*')}", line)
 
 
 _line_formatter = LineFormatter()

robotcode_robot-2.9.0.dev115/src/robotcode/robot/__version__.py

@@ -1 +0,0 @@
-__version__ = "2.9.0-dev.115"