Make the linker always output link tags only. No <code> tags. The <code> tags are now added by the html translator when the document is a docstring. Otherwise it does not add the enclosing <code> tags because we're already in the middle of a code tag or similar <span class="rst-literal">.

tristanlatr · tristanlatr · commit ec6c907c59d9 · 2025-02-02T14:26:47.000-05:00
Adjust the themes so the &lt;code&gt; tags and &lt;span class="rst-literal"&gt; are really equivalent.
diff --git a/pydoctor/epydoc/docutils.py b/pydoctor/epydoc/docutils.py
@@ -3,7 +3,10 @@
 """
 from __future__ import annotations
 
-from typing import Iterable, Iterator, Optional, TypeVar, cast
+from typing import Iterable, Iterator, Optional, TypeVar, cast, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Literal
 
 import optparse
 
@@ -14,11 +17,11 @@
 
 _DEFAULT_DOCUTILS_SETTINGS: Optional[optparse.Values] = None
 
-def new_document(source_path: str, settings: Optional[optparse.Values] = None) -> nodes.document:
+def new_document(source: Literal['docstring', 'code'], settings: Optional[optparse.Values] = None) -> nodes.document:
     """
     Create a new L{nodes.document} using the provided settings or cached default settings.
 
-    @returns: L{nodes.document}
+    @returns: L{nodes.document} which a C{source} attribute that matches the provided source.
     """
     global _DEFAULT_DOCUTILS_SETTINGS
     # If we have docutils >= 0.19 we use get_default_settings to calculate and cache
@@ -29,7 +32,7 @@ def new_document(source_path: str, settings: Optional[optparse.Values] = None) -
 
         settings = _DEFAULT_DOCUTILS_SETTINGS
 
-    return utils.new_document(source_path, settings)
+    return utils.new_document(source, settings)
 
 def _set_nodes_parent(nodes: Iterable[nodes.Node], parent: nodes.Element) -> Iterator[nodes.Node]:
     """
diff --git a/pydoctor/epydoc/markup/__init__.py b/pydoctor/epydoc/markup/__init__.py
@@ -150,7 +150,8 @@ def __init__(self, fields: Sequence['Field']):
         self._stan: Optional[Tag] = None
         self._summary: Optional['ParsedDocstring'] = None
 
-    @abc.abstractproperty
+    @property
+    @abc.abstractmethod
     def has_body(self) -> bool:
         """
         Does this docstring have a non-empty body?
@@ -168,7 +169,7 @@ def get_toc(self, depth: int) -> Optional['ParsedDocstring']:
         except NotImplementedError:
             return None
         contents = build_table_of_content(document, depth=depth)
-        docstring_toc = new_document('toc')
+        docstring_toc = new_document('docstring')
         if contents:
             docstring_toc.extend(contents)
             from pydoctor.epydoc.markup.restructuredtext import ParsedRstDocstring
@@ -439,7 +440,7 @@ def visit_paragraph(self, node: nodes.paragraph) -> None:
             self.other_docs = True
             raise nodes.StopTraversal()
 
-        summary_doc = new_document('summary')
+        summary_doc = new_document('docstring')
         summary_pieces: list[nodes.Node] = []
 
         # Extract the first sentences from the first paragraph until maximum number 
diff --git a/pydoctor/epydoc/markup/_pyval_repr.py b/pydoctor/epydoc/markup/_pyval_repr.py
@@ -333,7 +333,7 @@ def colorize(self, pyval: Any) -> ColorizedPyvalRepr:
             is_complete = True
         
         # Put it all together.
-        document = new_document('pyval_repr')
+        document = new_document('code')
         # This ensure the .parent and .document attributes of the child nodes are set correcly.
         set_node_attributes(document, children=[set_node_attributes(node, document=document) for node in state.result])
         return ColorizedPyvalRepr(document, is_complete, state.warnings)
diff --git a/pydoctor/epydoc/markup/epytext.py b/pydoctor/epydoc/markup/epytext.py
@@ -1379,7 +1379,7 @@ def to_node(self) -> nodes.document:
         if self._document is not None:
             return self._document
 
-        self._document = new_document('epytext')
+        self._document = new_document('docstring')
 
         if self._tree is not None:
             node, = self._to_node(self._tree)
diff --git a/pydoctor/epydoc/markup/plaintext.py b/pydoctor/epydoc/markup/plaintext.py
@@ -62,7 +62,7 @@ def to_node(self) -> nodes.document:
             return self._document
         else:
             # create document
-            _document = new_document('plaintext')
+            _document = new_document('docstring')
 
             # split text into paragraphs
             paragraphs = [set_node_attributes(nodes.paragraph('',''), children=[
diff --git a/pydoctor/epydoc/markup/restructuredtext.py b/pydoctor/epydoc/markup/restructuredtext.py
@@ -176,7 +176,7 @@ def get_transforms(self) -> List[Transform]:
                 if t != frontmatter.DocInfo]
 
     def new_document(self) -> nodes.document:
-        document = new_document(self.source.source_path, self.settings)
+        document = new_document('docstring', self.settings)
         # Capture all warning messages.
         document.reporter.attach_observer(self.report)
         # Return the new document.
diff --git a/pydoctor/epydoc2stan.py b/pydoctor/epydoc2stan.py
@@ -1155,7 +1155,7 @@ def get_constructors_extra(cls:model.Class) -> ParsedDocstring | None:
     if not constructors:
         return None
     
-    document = new_document('constructors')
+    document = new_document('docstring')
 
     elements: list[nodes.Node] = []
     plural = 's' if len(constructors)>1 else ''
diff --git a/pydoctor/linker.py b/pydoctor/linker.py
@@ -153,14 +153,14 @@ def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
         try:
             resolved = self._resolve_identifier_xref(target, lineno)
         except LookupError:
-            xref = label
+            xref = tags.transparent(label)
         else:
             if isinstance(resolved, str):
                 xref = intersphinx_link(label, url=resolved)
             else:
                 xref = taglink(resolved, self.page_url, label)
                 
-        return tags.code(xref)
+        return xref
 
     def _resolve_identifier_xref(self,
             identifier: str,
@@ -286,13 +286,17 @@ def switch_context(self, ob:Optional['model.Documentable']) -> Iterator[None]:
             yield
 
 class NotFoundLinker(DocstringLinker):
-    """A DocstringLinker implementation that cannot find any links."""
+    """
+    A DocstringLinker implementation that cannot find any links.
+    
+    It will always output link tag with no C{href} attribute.
+    """
 
     def link_to(self, target: str, label: "Flattenable") -> Tag:
-        return tags.transparent(label)
+        return tags.a(label)
 
     def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
-        return tags.code(label)
+        return tags.a(label)
     
     @contextlib.contextmanager
     def switch_context(self, ob: Optional[model.Documentable]) -> Iterator[None]:
diff --git a/pydoctor/node2stan.py b/pydoctor/node2stan.py
@@ -102,10 +102,20 @@ def __init__(self,
         # h1 is reserved for the page nodes.title. 
         self.section_level += 1
 
+        # All documents should be created with pydoctor.epydoc.docutils.new_document() helper
+        # such that the source attribute will always be one of the supported values.
+        self._document_is_code = is_code = document.attributes.get('source') == 'code'
+        if is_code:
+            # Do not wrap links in <code> tags if we're renderring a code-like parsed element.
+            self._link_xref = self._linker.link_xref
+        else:
+            self._link_xref = lambda target, label, lineno: Tag('code')(self._linker.link_xref(target, label, lineno))
+
+
     # Handle interpreted text (crossreferences)
     def visit_title_reference(self, node: nodes.title_reference) -> None:
         lineno = get_lineno(node)
-        self._handle_reference(node, link_func=lambda target, label: self._linker.link_xref(target, label, lineno))
+        self._handle_reference(node, link_func=lambda target, label: self._link_xref(target, label, lineno))
     
     # Handle internal references
     def visit_obj_reference(self, node: obj_reference) -> None:
@@ -134,6 +144,8 @@ def _handle_reference(self, node: nodes.title_reference, link_func: Callable[[st
     def should_be_compact_paragraph(self, node: nodes.Element) -> bool:
         if self.document.children == [node]:
             return True
+        elif self._document_is_code:
+            return True
         else:
             return super().should_be_compact_paragraph(node)  # type: ignore[no-any-return]
 
diff --git a/pydoctor/test/test_astbuilder.py b/pydoctor/test/test_astbuilder.py
@@ -1339,25 +1339,25 @@ def __init__(self):
     assert type2html(b) == 'string'
     c = C.contents['c']
     assert c.docstring == """third"""
-    assert type2html(c) == '<code>str</code>'
+    assert type2html(c) == '<code><a>str</a></code>'
     d = C.contents['d']
     assert d.docstring == """fourth"""
-    assert type2html(d) == '<code>str</code>'
+    assert type2html(d) == '<code><a>str</a></code>'
     e = C.contents['e']
     assert e.docstring == """fifth"""
-    assert type2html(e) == '<code>List[C]</code>'
+    assert type2html(e) == '<code><a>List</a>[<a>C</a>]</code>'
     f = C.contents['f']
     assert f.docstring == """sixth"""
-    assert type2html(f) == '<code>List[C]</code>'
+    assert type2html(f) == '<code><a>List</a>[<a>C</a>]</code>'
     g = C.contents['g']
     assert g.docstring == """seventh"""
-    assert type2html(g) == '<code>List[C]</code>'
+    assert type2html(g) == '<code><a>List</a>[<a>C</a>]</code>'
     s = C.contents['s']
     assert s.docstring == """instance"""
-    assert type2html(s) == '<code>List[str]</code>'
+    assert type2html(s) == '<code><a>List</a>[<a>str</a>]</code>'
     m = mod.contents['m']
     assert m.docstring == """module-level"""
-    assert type2html(m) == '<code>bytes</code>'
+    assert type2html(m) == '<code><a>bytes</a></code>'
 
 @systemcls_param
 def test_type_comment(systemcls: Type[model.System], capsys: CapSys) -> None:
diff --git a/pydoctor/test/test_epydoc2stan.py b/pydoctor/test/test_epydoc2stan.py
@@ -1101,7 +1101,7 @@ def test_EpydocLinker_adds_intersphinx_link_css_class() -> None:
     sut = target.docstring_linker
     assert isinstance(sut, linker._EpydocLinker)
 
-    result1 = sut.link_xref('base.module.other', 'base.module.other', 0).children[0] # wrapped in a code tag
+    result1 = sut.link_xref('base.module.other', 'base.module.other', 0)
     result2 = sut.link_to('base.module.other', 'base.module.other')
     
     res = flatten(result2)
diff --git a/pydoctor/test/test_zopeinterface.py b/pydoctor/test/test_zopeinterface.py
@@ -198,15 +198,15 @@ class IMyInterface(interface.Interface):
     mod = fromText(src, modname='mod', systemcls=systemcls)
     text = mod.contents['IMyInterface'].contents['text']
     assert text.docstring == 'fun in a bun'
-    assert type2html(text)==  "<code>schema.TextLine</code>"
+    assert type2html(text)==  "<code><a>schema.TextLine</a></code>"
     assert text.kind is model.DocumentableKind.SCHEMA_FIELD
     undoc = mod.contents['IMyInterface'].contents['undoc']
     assert undoc.docstring is None
-    assert type2html(undoc) == "<code>schema.Bool</code>"
+    assert type2html(undoc) == "<code><a>schema.Bool</a></code>"
     assert undoc.kind is model.DocumentableKind.SCHEMA_FIELD
     bad = mod.contents['IMyInterface'].contents['bad']
     assert bad.docstring is None
-    assert type2html(bad) == "<code>schema.ASCII</code>"
+    assert type2html(bad) == "<code><a>schema.ASCII</a></code>"
     assert bad.kind is model.DocumentableKind.SCHEMA_FIELD
     captured = capsys.readouterr().out
     assert captured == 'mod:6: description of field "bad" is not a string literal\n'
@@ -241,14 +241,14 @@ class IMyInterface(interface.Interface):
     mod = fromText(src, modname='mod', systemcls=systemcls)
     mytext = mod.contents['IMyInterface'].contents['mytext']
     assert mytext.docstring == 'fun in a bun'
-    assert flatten(cast(ParsedDocstring, mytext.parsed_type).to_stan(NotFoundLinker())) == "<code>MyTextLine</code>"
+    assert flatten(cast(ParsedDocstring, mytext.parsed_type).to_stan(NotFoundLinker())) == '<code><a>MyTextLine</a></code>'
     assert mytext.kind is model.DocumentableKind.SCHEMA_FIELD
     myothertext = mod.contents['IMyInterface'].contents['myothertext']
     assert myothertext.docstring == 'fun in another bun'
-    assert flatten(cast(ParsedDocstring, myothertext.parsed_type).to_stan(NotFoundLinker())) == "<code>MyOtherTextLine</code>"
+    assert flatten(cast(ParsedDocstring, myothertext.parsed_type).to_stan(NotFoundLinker())) == "<code><a>MyOtherTextLine</a></code>"
     assert myothertext.kind is model.DocumentableKind.SCHEMA_FIELD
     myint = mod.contents['IMyInterface'].contents['myint']
-    assert flatten(cast(ParsedDocstring, myint.parsed_type).to_stan(NotFoundLinker())) == "<code>INTEGERSCHMEMAFIELD</code>"
+    assert flatten(cast(ParsedDocstring, myint.parsed_type).to_stan(NotFoundLinker())) == "<code><a>INTEGERSCHMEMAFIELD</a></code>"
     assert myint.kind is model.DocumentableKind.SCHEMA_FIELD
 
 @zope_interface_systemcls_param
diff --git a/pydoctor/themes/base/apidocs.css b/pydoctor/themes/base/apidocs.css
@@ -264,7 +264,7 @@ ul ul ul ul ul ul ul {
 }
 
 /* parameters types (in parameters table) */
-.fieldTable tr td.fieldArgContainer > code {
+.fieldTable tr td.fieldArgContainer > code, .fieldTable tr td.fieldArgContainer > .rst-literal {
     /* we don't want word break for the types because we already add <wbr> tags inside the type HTML, and that should suffice. */
     word-break: normal;
     display: inline;
@@ -427,7 +427,7 @@ code, .rst-literal, .pre, #childList > div .functionHeader,
 #splitTables > table tr td:nth-child(2), .fieldArg {
     font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
 }
-code, #childList > div .functionHeader, .fieldArg {
+code, .rst-literal, #childList > div .functionHeader, .fieldArg {
     color: #222222;
 }
 
@@ -469,7 +469,8 @@ It also overwrite the default values inherited from bootstrap min
 code, .rst-literal {
     padding:2px 4px;
     background-color: #f4f4f4;
-    border-radius:4px
+    border-radius:4px;
+    font-size: 90%; /* <code> and class="rst-literal" are closely equivalent */
 }
 
 
diff --git a/pydoctor/themes/readthedocs/readthedocstheme.css b/pydoctor/themes/readthedocs/readthedocstheme.css
@@ -92,12 +92,12 @@ code, .pre, #childList > div .functionHeader,
     font-family: Menlo, Monaco, Consolas, "Courier New", monospace;
 }
 
-code, .literal {
+code, .literal, .rst-literal {
     border-radius:2px;
     font-size: 14px;
 }
 
-#main code, .literal {
+#main code, .literal, .rst-literal {
     border: 1px solid rgb(225, 228, 229);
     padding:1px 2px;
 }
