Pre-process parsed docstrings to add hints on how to resolve names

pydoctor/astbuilder.py

@@ -257,6 +257,7 @@ def depart_Module(self, node: ast.Module) -> None:
         self._tweak_constants_annotations(self.builder.current)
         self._infer_attr_annotations(self.builder.current)
         self.builder.pop(self.module)
+        epydoc2stan.transform_parsed_names(self.module)
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         # Ignore classes within functions.
@@ -1153,6 +1154,8 @@ def _get_all_ast_annotations() -> Iterator[Tuple[str, Optional[ast.expr]]]:
 class ASTBuilder:
     """
     Keeps tracks of the state of the AST build, creates documentable and adds objects to the system.
+
+    One ASTBuilder instance is only suitable to build one Module.
     """
     ModuleVistor = ModuleVistor
 
@@ -1164,21 +1167,6 @@ def __init__(self, system: model.System):
 
         self._stack: List[model.Documentable] = []
 
-
-    def parseFile(self, path: Path, ctx: model.Module) -> Optional[ast.Module]:
-        try:
-            return self.system._ast_parser.parseFile(path)
-        except Exception as e:
-            ctx.report(f"cannot parse file, {e}")
-            return None
-
-    def parseString(self, string:str, ctx: model.Module) -> Optional[ast.Module]:
-        try:
-            return self.system._ast_parser.parseString(string)
-        except Exception:
-            ctx.report("cannot parse string")
-            return None
-
     def _push(self, 
               cls: Type[DocumentableT], 
               name: str, 
@@ -1270,14 +1258,6 @@ def addAttribute(self,
 
     def processModuleAST(self, mod_ast: ast.Module, mod: model.Module) -> None:
 
-        for name, node in findModuleLevelAssign(mod_ast):
-            try:
-                module_var_parser = MODULE_VARIABLES_META_PARSERS[name]
-            except KeyError:
-                continue
-            else:
-                module_var_parser(node, mod)
-
         vis = self.ModuleVistor(self, mod)
         vis.extensions.add(*self.system._astbuilder_visitors)
         vis.extensions.attach_visitor(vis)
@@ -1304,7 +1284,7 @@ def exception(self) -> Exception:
     def __init__(self) -> None:
         self.ast_cache: Dict[Path, ast.Module | SyntaxTreeParser._Error] = {}
 
-    def parseFile(self, path: Path) -> ast.Module:
+    def parseFileOnly(self, path: Path) -> ast.Module:
         try:
             r = self.ast_cache[path]
         except KeyError:
@@ -1322,14 +1302,28 @@ def parseFile(self, path: Path) -> ast.Module:
                 raise r.exception()
             return r
 
-    def parseString(self, string:str) -> ast.Module:
+    def parseStringOnly(self, string:str) -> ast.Module:
         mod = None
         try:
             mod = _parse(string)
         except (SyntaxError, ValueError) as e:
             raise SyntaxError("cannot parse string") from e
         return mod
 
+    def parseFile(self, path: Path, ctx: model.Module) -> model.ParsedAstModule | None:
+        try:
+            return model.ParsedAstModule(self.parseFileOnly(path))
+        except Exception as e:
+            ctx.report(f"cannot parse file, {e}")
+            return None
+
+    def parseString(self, string:str, ctx: model.Module) -> model.ParsedAstModule | None:
+        try:
+            return model.ParsedAstModule(self.parseStringOnly(string))
+        except Exception:
+            ctx.report("cannot parse string")
+            return None
+
 model.System.defaultBuilder = ASTBuilder
 model.System.syntaxTreeParser = SyntaxTreeParser
 

pydoctor/epydoc/markup/__init__.py

@@ -315,7 +315,7 @@ def link_to(self, target: str, label: "Flattenable", *, is_annotation: bool = Fa
         @return: The link, or just the label if the target was not found.
         """
 
-    def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
+    def link_xref(self, target: str, label: "Flattenable", lineno: int, rawtarget: str | None = None) -> Tag:
         """
         Format a cross-reference link to a Python identifier.
         This will resolve the identifier to any reasonable target,
@@ -326,8 +326,10 @@ def link_xref(self, target: str, label: "Flattenable", lineno: int) -> Tag:
         @param label: The label to show for the link.
         @param lineno: The line number within the docstring at which the
             crossreference is located.
+        @param rawtarget: The name of the Python identifier that
+            should be linked to, as written in the docstring, for warning purposes.
+            If it's left None, the C{identifier} will be used instead.
         @return: The link, or just the label if the target was not found.
-            In either case, the returned top-level tag will be C{<code>}.
         """
 
     def switch_context(self, ob:Optional['Documentable']) -> ContextManager[None]: