👌 Reference attributes title -> reftitle (#666)

Sphinx will output reftitle as the HTML title attr.
See: https://github.com/sphinx-doc/sphinx/blob/6e6b9ad45194177811551c77f5f4040213d1c661/sphinx/writers/html5.py#L227

docs/syntax/optional.md

@@ -760,7 +760,7 @@ For example, the following Markdown:
 - `A literal with attributes`{#literalid .bg-warning},
   {ref}`a reference to the literal <literalid>
 
-- An autolink with attributes: <https://example.com>{.bg-warning}
+- An autolink with attributes: <https://example.com>{.bg-warning title="a title"}
 
 - [A link with attributes](syntax/attributes){#linkid .bg-warning},
   {ref}`a reference to the link <linkid>`
@@ -778,7 +778,7 @@ will be parsed as:
 - `A literal with attributes`{#literalid .bg-warning},
   {ref}`a reference to the literal <literalid>`
 
-- An autolink with attributes: <https://example.com>{.bg-warning}
+- An autolink with attributes: <https://example.com>{.bg-warning title="a title"}
 
 - [A link with attributes](syntax/attributes){#linkid .bg-warning},
   {ref}`a reference to the link <linkid>`

myst_parser/mdit_to_docutils/base.py

@@ -379,7 +379,14 @@ def copy_attributes(
         converters: dict[str, Callable[[str], Any]] | None = None,
         aliases: dict[str, str] | None = None,
     ) -> None:
-        """Copy attributes on the token to the docutils node."""
+        """Copy attributes on the token to the docutils node.
+
+        :param token: the token to copy attributes from
+        :param node: the node to copy attributes to
+        :param keys: the keys to copy from the token (after aliasing)
+        :param converters: a dictionary of converters for the attributes
+        :param aliases: a dictionary mapping the token key name to the node key name
+        """
         if converters is None:
             converters = {}
         if aliases is None:
@@ -751,7 +758,9 @@ def render_external_url(self, token: SyntaxTreeNode) -> None:
         """
         ref_node = nodes.reference()
         self.add_line_and_source_path(ref_node, token)
-        self.copy_attributes(token, ref_node, ("class", "id", "title"))
+        self.copy_attributes(
+            token, ref_node, ("class", "id", "reftitle"), aliases={"title": "reftitle"}
+        )
         ref_node["refuri"] = cast(str, token.attrGet("href") or "")
         with self.current_node_context(ref_node, append=True):
             self.render_children(token)
@@ -769,7 +778,9 @@ def render_internal_link(self, token: SyntaxTreeNode) -> None:
         """
         ref_node = nodes.reference()
         self.add_line_and_source_path(ref_node, token)
-        self.copy_attributes(token, ref_node, ("class", "id", "title"))
+        self.copy_attributes(
+            token, ref_node, ("class", "id", "reftitle"), aliases={"title": "reftitle"}
+        )
         ref_node["refname"] = cast(str, token.attrGet("href") or "")
         self.document.note_refname(ref_node)
         with self.current_node_context(ref_node, append=True):
@@ -778,7 +789,9 @@ def render_internal_link(self, token: SyntaxTreeNode) -> None:
     def render_autolink(self, token: SyntaxTreeNode) -> None:
         refuri = escapeHtml(token.attrGet("href") or "")  # type: ignore[arg-type]
         ref_node = nodes.reference()
-        self.copy_attributes(token, ref_node, ("class", "id"))
+        self.copy_attributes(
+            token, ref_node, ("class", "id", "reftitle"), aliases={"title": "reftitle"}
+        )
         ref_node["refuri"] = refuri
         self.add_line_and_source_path(ref_node, token)
         with self.current_node_context(ref_node, append=True):

tests/test_renderers/fixtures/docutil_syntax_elements.md

@@ -376,7 +376,7 @@ Link Reference:
 .
 <document source="notset">
     <paragraph>
-        <reference refuri="https://www.google.com" title="a title">
+        <reference reftitle="a title" refuri="https://www.google.com">
             name
 .
 
@@ -388,7 +388,7 @@ Link Reference short version:
 .
 <document source="notset">
     <paragraph>
-        <reference refuri="https://www.google.com" title="a title">
+        <reference reftitle="a title" refuri="https://www.google.com">
             name
 .
 

tests/test_renderers/fixtures/sphinx_syntax_elements.md

@@ -379,7 +379,7 @@ Link Reference:
 .
 <document source="<src>/index.md">
     <paragraph>
-        <reference refuri="https://www.google.com" title="a title">
+        <reference reftitle="a title" refuri="https://www.google.com">
             name
 .
 
@@ -391,7 +391,7 @@ Link Reference short version:
 .
 <document source="<src>/index.md">
     <paragraph>
-        <reference refuri="https://www.google.com" title="a title">
+        <reference reftitle="a title" refuri="https://www.google.com">
             name
 .
 

tests/test_sphinx/test_sphinx_builds/test_basic.html

@@ -229,7 +229,7 @@ <h1>
      </a>
     </p>
     <p>
-     <a class="reference external" href="https://www.google.com">
+     <a class="reference external" href="https://www.google.com" title="a title">
       name
      </a>
     </p>

tests/test_sphinx/test_sphinx_builds/test_basic.resolved.xml

@@ -140,7 +140,7 @@
         <comment classes="block_break" xml:space="preserve">
             a block break
         <paragraph>
-            <reference refuri="https://www.google.com" title="a title">
+            <reference reftitle="a title" refuri="https://www.google.com">
                 name
         <literal_block language="default" linenos="False" xml:space="preserve">
             def func(a, b=1):

tests/test_sphinx/test_sphinx_builds/test_basic.xml

@@ -141,7 +141,7 @@
         <comment classes="block_break" xml:space="preserve">
             a block break
         <paragraph>
-            <reference refuri="https://www.google.com" title="a title">
+            <reference reftitle="a title" refuri="https://www.google.com">
                 name
         <literal_block language="default" xml:space="preserve">
             def func(a, b=1):