robotcode-robot 2.9.0.dev115__py3-none-any.whl → 2.9.0.dev124__py3-none-any.whl

robotcode/robot/__version__.py

@@ -1 +1 @@
-__version__ = "2.9.0-dev.115"
+__version__ = "2.9.0-dev.124"

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/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/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.dist-info → robotcode_robot-2.9.0.dev124.dist-info}/METADATA

@@ -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.dist-info → robotcode_robot-2.9.0.dev124.dist-info}/RECORD

@@ -1,5 +1,5 @@
 robotcode/robot/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-robotcode/robot/__version__.py,sha256=qCMGA7BDTVyBevZ0ksnNoqFh10zoIu3X15NTXaUZz8M,30
+robotcode/robot/__version__.py,sha256=kB2HCucrVBrLij9hB2UXa9rwCOmEfmeDk12kUWayuAU,30
 robotcode/robot/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
 robotcode/robot/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 robotcode/robot/config/loader.py,sha256=HLbkZem8JiBuy9Q5naghZddAuMPOn8Tk6UBgN2T3Uyc,9073
@@ -16,7 +16,7 @@ robotcode/robot/diagnostics/errors.py,sha256=lqHDWrMNy3ZhuEIVxeEhaU0ns8PB6pVTQBf
 robotcode/robot/diagnostics/import_resolver.py,sha256=DZjUOD3uNxFAwsVUqrCTRhColjz9DRPetAvIb_Ccufs,32588
 robotcode/robot/diagnostics/imports_manager.py,sha256=opemApuCLgPNsnqVuYc9MefqHt42g_7Ozqhrmu_osH0,90401
 robotcode/robot/diagnostics/keyword_finder.py,sha256=nwTmjvhyu5H7HHzyk8gt-pny2K2xdH2qCNyKXwwXRnk,18998
-robotcode/robot/diagnostics/library_doc.py,sha256=ZoAiT8zwHMXo8LpEnBy_xP7Tdth_9gopntEaqWzgxHI,153578
+robotcode/robot/diagnostics/library_doc.py,sha256=loLZ7cJjtrNn6YXv_lC8SmptfIUK7P5Hkdc782opN9k,153586
 robotcode/robot/diagnostics/model_helper.py,sha256=_ySXwerkK5xvjWa82T0DFy8jpxRzcaavTJiAHnk2lXQ,29740
 robotcode/robot/diagnostics/namespace.py,sha256=Rcmjk3V0vcY-DUkgjkRyuOdYXurKaTEqXJLc6efYrwY,35489
 robotcode/robot/diagnostics/namespace_analyzer.py,sha256=dGAEbbznPJlFBKN4dLkMDU7w9xc0mYdmRARvRS3Zlwg,104331
@@ -35,14 +35,14 @@ robotcode/robot/diagnostics/semantic_analyzer/serialization.py,sha256=DA-_gRbo_9
 robotcode/robot/diagnostics/semantic_analyzer/variable_tokenizer.py,sha256=vBor3GZjvZX33I9yQliUtHZbjDybWn7W0YoSd5EMO_M,33646
 robotcode/robot/utils/__init__.py,sha256=-A0YeHv7e7WK1SId7Er7Vu6frrDYWopUrcyFlyxLmPY,396
 robotcode/robot/utils/ast.py,sha256=S9xyiJZee4Y5VcroNrGIIWp8f9sutb_1o4blAlCqzdg,11218
-robotcode/robot/utils/markdown_docs.py,sha256=0xRa79quMMuQRKjFBHwPPDCF6_0aYOT0YDAo_2MmHNE,30075
-robotcode/robot/utils/markdownformatter.py,sha256=5yCrnHhJ3hIAWUjNw6yUZfhgjWGkNboWRWd64uBDzqI,16036
+robotcode/robot/utils/markdown_docs.py,sha256=jR1gfOAyf0C6i-Gn9Q2cStHogAUXcM-jFNu2Uv7uhZE,31424
+robotcode/robot/utils/markdownformatter.py,sha256=HjFLZK1whOghijdKAyw3NciCI_JrCmlUtst1rl8VTMA,17390
 robotcode/robot/utils/match.py,sha256=KgA6o6TbnQpOT1eAzEjhl_-FZ2XO07xiV0L7IYRzyzE,1125
 robotcode/robot/utils/robot_patching.py,sha256=jXHhnPvZx8hCQq4B_2uwX9j51Be_toWpUoTYYe8HjPo,1463
 robotcode/robot/utils/robot_path.py,sha256=ObLP8PqamTZAz5oi0eDXE_dnyZwAPXp4TJYm6ugeENs,2185
 robotcode/robot/utils/stubs.py,sha256=umugZYAyneFNgqRJBRMJPzm0u0B_TH8Sx_y-ykXnxpw,351
 robotcode/robot/utils/variables.py,sha256=9WnP3QqcHdq-zioJ_gJXJobw_2Gcto_rGPCUGmOH9YQ,9829
 robotcode/robot/utils/visitor.py,sha256=nP3O0qh3YYuxR6S8wYJRBFfNwIVgsgohURBlrnFkRYQ,2299
-robotcode_robot-2.9.0.dev115.dist-info/METADATA,sha256=qcJxc40nb6sN31qCIQ42UPujJyMOZX7izWc95ibtBk8,2960
-robotcode_robot-2.9.0.dev115.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
-robotcode_robot-2.9.0.dev115.dist-info/RECORD,,
+robotcode_robot-2.9.0.dev124.dist-info/METADATA,sha256=cmy8fBqH5dS-DWv3D33XiFGSB7EF97b0iqoDFDH4xOw,2960
+robotcode_robot-2.9.0.dev124.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+robotcode_robot-2.9.0.dev124.dist-info/RECORD,,