bug: External cross-references are rendered as links to nowhere

[jayqi]

Description of the bug

All type annotations for any types get generated as hyperlinks with header ID fragments, but the links for types that are external to the package don't go to real header in the document. This is confusing because these appear as hyperlinks that don't do anything.

To Reproduce

This docstring:

def read_version_from_pyproject_toml(path: Path) -> Version:
    """Read the version from a pyproject.toml file. Requires the version to be statically defined.

    Args:
        path (Path): The path to the pyproject.toml file, or the directory containing it.

    Returns:
        (packaging.version.Version): The version read from the file.
    """

produces this output:

### vspect.read_version_from_pyproject_toml

```python
read_version_from_pyproject_toml(path)
```

Read the version from a pyproject.toml file. Requires the version to be statically defined.

**Parameters:**

- **path** (<code>[Path](#pathlib.Path)</code>) – The path to the pyproject.toml file, or the directory containing it.

**Returns:**

- <code>[Version](#packaging.version.Version)</code> – The version read from the file.

The hyperlinks [Path](#pathlib.Path) and [Version](#packaging.version.Version) don't link to real headers in the document. (The extraneous periods as reported in #3 notwithstanding.)

Full output

Expected behavior

External type annotations should not be hyperlinks.

A nice-to-have would be to link to external documentation.

Environment information

• System: macOS-14.7.2-x86_64-i386-64bit-Mach-O
• Python: cpython 3.13.0 (/Users/jqi/vspect/.venv/bin/python3)
• Environment variables:
• Installed packages:
  • griffe2md v1.1.0

[pawamoy]

I believe the fix for #3 will also allow us to fix this. By rendering temporary "autoref" elements that we later fix, we'll be able to avoid writing links for objects that weren't rendered.

In subsequent work we can try to bring the inventory loading capabilities of mkdocstrings(-python) into griffe2md 🙂 I wonder if there's a way to at least reuse mkdocs-autorefs, so that we don't have to replicate all its features here.

I'll mark this as a feature request rather than a bug.