Merge pull request #56120 from timothyqiu/make-rst-3.x

doc/tools/make_rst.py

@@ -14,6 +14,11 @@ from collections import OrderedDict
 # $DOCS_URL/path/to/page.html(#fragment-tag)
 GODOT_DOCS_PATTERN = re.compile(r"^\$DOCS_URL/(.*)\.html(#.*)?$")
 
+# Based on reStructedText inline markup recognition rules
+# https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules
+MARKUP_ALLOWED_PRECEDENT = " -:/'\"<([{"
+MARKUP_ALLOWED_SUBSEQUENT = " -.,:;!?\\/'\")]}>"
+
 
 def print_error(error, state):  # type: (str, State) -> None
     print("ERROR: {}".format(error))
@@ -715,12 +720,12 @@ def rstize_text(text, state):  # type: (str, State) -> str
                     code_pos += 5 - to_skip
 
             text = pre_text + "\n[codeblock]" + code_text + post_text
-            pos += len("\n[codeblock]" + code_text)
+            pos += len("\n[codeblock]" + code_text) - indent_level
 
         # Handle normal text
         else:
             text = pre_text + "\n\n" + post_text
-            pos += 2
+            pos += 2 - indent_level
 
     next_brac_pos = text.find("[")
     text = escape_rst(text, next_brac_pos)
@@ -743,6 +748,7 @@ def rstize_text(text, state):  # type: (str, State) -> str
         post_text = text[endq_pos + 1 :]
         tag_text = text[pos + 1 : endq_pos]
 
+        escape_pre = False
         escape_post = False
 
         if tag_text in state.classes:
@@ -751,6 +757,7 @@ def rstize_text(text, state):  # type: (str, State) -> str
                 tag_text = "``{}``".format(tag_text)
             else:
                 tag_text = make_type(tag_text, state)
+            escape_pre = True
             escape_post = True
         else:  # command
             cmd = tag_text
@@ -846,6 +853,7 @@ def rstize_text(text, state):  # type: (str, State) -> str
                 if class_param != state.current_class:
                     repl_text = "{}.{}".format(class_param, method_param)
                 tag_text = ":ref:`{}<class_{}{}_{}>`".format(repl_text, class_param, ref_type, method_param)
+                escape_pre = True
                 escape_post = True
             elif cmd.find("image=") == 0:
                 tag_text = ""  # '![](' + cmd[6:] + ')'
@@ -863,7 +871,14 @@ def rstize_text(text, state):  # type: (str, State) -> str
                 tag_text = make_link(link_url, link_title)
 
                 pre_text = text[:pos]
-                text = pre_text + tag_text + text[endurl_pos + 6 :]
+                post_text = text[endurl_pos + 6 :]
+
+                if pre_text and pre_text[-1] not in MARKUP_ALLOWED_PRECEDENT:
+                    pre_text += "\ "
+                if post_text and post_text[0] not in MARKUP_ALLOWED_SUBSEQUENT:
+                    post_text = "\ " + post_text
+
+                text = pre_text + tag_text + post_text
                 pos = len(pre_text) + len(tag_text)
                 previous_pos = pos
                 continue
@@ -886,34 +901,45 @@ def rstize_text(text, state):  # type: (str, State) -> str
             elif cmd == "i" or cmd == "/i":
                 if cmd == "/i":
                     tag_depth -= 1
+                    escape_post = True
                 else:
                     tag_depth += 1
+                    escape_pre = True
                 tag_text = "*"
             elif cmd == "b" or cmd == "/b":
                 if cmd == "/b":
                     tag_depth -= 1
+                    escape_post = True
                 else:
                     tag_depth += 1
+                    escape_pre = True
                 tag_text = "**"
             elif cmd == "u" or cmd == "/u":
                 if cmd == "/u":
                     tag_depth -= 1
+                    escape_post = True
                 else:
                     tag_depth += 1
+                    escape_pre = True
                 tag_text = ""
             elif cmd == "code":
                 tag_text = "``"
                 tag_depth += 1
                 inside_code = True
+                escape_pre = True
             elif cmd.startswith("enum "):
                 tag_text = make_enum(cmd[5:], state)
+                escape_pre = True
                 escape_post = True
             else:
                 tag_text = make_type(tag_text, state)
+                escape_pre = True
                 escape_post = True
 
         # Properly escape things like `[Node]s`
-        if escape_post and post_text and (post_text[0].isalnum() or post_text[0] == "("):  # not punctuation, escape
+        if escape_pre and pre_text and pre_text[-1] not in MARKUP_ALLOWED_PRECEDENT:
+            pre_text += "\ "
+        if escape_post and post_text and post_text[0] not in MARKUP_ALLOWED_SUBSEQUENT:
             post_text = "\ " + post_text
 
         next_brac_pos = post_text.find("[", 0)