Add tests for :manpage: inside a title

CHANGES.rst

@@ -36,6 +36,8 @@ Bugs fixed
   Patch by Bénédikt Tran.
 * #11697: HTML Search: add 'noindex' meta robots tag.
   Patch by James Addison.
+* #11673: html builder: Allow :rst:role:`manpage` markup inside an RST title.
+  Patch by Bénédikt Tran.
 
 Testing
 -------

sphinx/builders/html/__init__.py

@@ -39,7 +39,7 @@
 from sphinx.theming import HTMLThemeFactory
 from sphinx.util import isurl, logging
 from sphinx.util.display import progress_message, status_iterator
-from sphinx.util.docutils import new_document
+from sphinx.util.docutils import new_document, new_partial_document
 from sphinx.util.fileutil import copy_asset
 from sphinx.util.i18n import format_date
 from sphinx.util.inventory import InventoryFile
@@ -425,7 +425,7 @@ def render_partial(self, node: Node | None) -> dict[str, str]:
         if node is None:
             return {'fragment': ''}
 
-        doc = new_document('<partial node>')
+        doc = new_partial_document()
         doc.append(node)
         self._publisher.set_source(doc)
         self._publisher.publish()

sphinx/util/docutils.py

@@ -566,6 +566,13 @@ def __init__(self, document: nodes.document, builder: Builder) -> None:
         self.builder = builder
         self.config = builder.config
         self.settings = document.settings
+        #: Indicate whether this translator is acting on a partial document
+        #: or not. This is typically useful when, in some visitor methods,
+        #: it is known that the method could be called from either a regular
+        #: document or a partial one which may not necessarily contain nodes
+        #: that were transformed (e.g., titles nodes stored by the environment
+        #: are not processed by Sphinx transformations).
+        self.in_partial_document = is_partial_document(document)
 
     def dispatch_visit(self, node: Node) -> None:
         """
@@ -633,3 +640,21 @@ def new_document(source_path: str, settings: Any = None) -> nodes.document:
     document = addnodes.document(settings, reporter, source=source_path)
     document.note_source(source_path, -1)
     return document
+
+
+def new_partial_document(settings: Any = None) -> nodes.document:
+    """Return a new empty partial document.
+
+    A partial document is a document with minimal capabilities and which
+    contains nodes that may not have been transformed by the docutils or
+    Sphinx transformations.
+
+    This function is typically used to render partial fragments of a doctree
+    using non-transformed information, e.g., the HTML ``<title>`` tag.
+    """
+    return new_document('<partial node>', settings)
+
+
+def is_partial_document(document: nodes.document) -> bool:
+    """Detect whether *document* is a partial document or not."""
+    return document.get('source') == '<partial node>'

sphinx/writers/html5.py

@@ -846,12 +846,12 @@ def depart_abbreviation(self, node: Element) -> None:
 
     def visit_manpage(self, node: Element) -> None:
         self.visit_literal_emphasis(node)
-        if self.manpages_url:
+        if not self.in_partial_document and self.manpages_url:
             node['refuri'] = self.manpages_url.format(**node.attributes)
             self.visit_reference(node)
 
     def depart_manpage(self, node: Element) -> None:
-        if self.manpages_url:
+        if not self.in_partial_document and self.manpages_url:
             self.depart_reference(node)
         self.depart_literal_emphasis(node)
 

tests/roots/test-manpage_url/index.rst

@@ -1,3 +1,5 @@
- * :manpage:`man(1)`
- * :manpage:`ls.1`
- * :manpage:`sphinx`
+The :manpage:`cp(1)`
+--------------------
+* :manpage:`man(1)`
+* :manpage:`ls.1`
+* :manpage:`sphinx`

tests/test_build_html.py

@@ -1492,7 +1492,8 @@ def test_html_sidebar(app, status, warning):
 
 
 @pytest.mark.parametrize(("fname", "expect"), flat_dict({
-    'index.html': [(".//em/a[@href='https://example.com/man.1']", "", True),
+    'index.html': [(".//h1/em/a[@href='https://example.com/cp.1']", "", True),
+                   (".//em/a[@href='https://example.com/man.1']", "", True),
                    (".//em/a[@href='https://example.com/ls.1']", "", True),
                    (".//em/a[@href='https://example.com/sphinx.']", "", True)],