docs: [Python] 型エイリアス系へのリンクについてワークアラウンド

[qryxip]

内容

関連 Issue

Resolves: #951

その他

数時間調べたけど、これ以外に方法は無さそう。

[Hiroshiba]

LGTM！！

よくわかってないのですが、これはautoapi.extensionではなくautodocでも同じように問題になるんですかね･･･？

---

将来sphinxのバージョンを上げたときなどに、いつの間にか動かなくなってるだろうなーと感じました。
ビルド後のドキュメントに対してリンクが貼られてるかのテストを書くか、conf.pyで予想外の動きをしたときにraiseするかした方が良いかも･･･？

まあ前者はビルド後のテストをどう書くべきなのか、後者は予想外をどう予想すれば良いのか課題はありますが。。。
とりあえずissue作るかTODO書くかだけでも、という気持ち！

[qryxip]

ちょっとどっちもキツそうではありますね。一番ありうるシナリオとしてはSphinx & Sphinx AutoAPIがちゃんと対応してワークアラウンドが要らなくなる、という感じな気が…

[qryxip]

よくわかってないのですが、これはautoapi.extensionではなくautodocでも同じように問題になるんですかね･･･？

ですね。型エイリアス系については、まあよくわからなかったのですが、なんかどうもSphinx本体とSphinx AutoAPIで別々の問題を抱えてるっぽく…

[Hiroshiba]

なるほどです･･･まあそうですよねぇ。

とりあえずやるなら、TARGETSそれぞれに対して１回以上Noneではないxrefが得られていればOK、そうじゃなければraise、とかかなぁ。

def _on_missing_reference(
    app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: TextElement
) -> reference | None:
    """
    `NewType や TypeAlias について class
    宛てにリンクしようとしてmissingになったものを、 `data 宛てに修正する。
    """
    # 参考: https://github.com/sphinx-doc/sphinx/issues/10785#issue-1348601826
    TARGETS = {
        "CharacterVersion",
        "StyleId",
        "VoiceModelId",
    }
    resolved_targets = {}  # 追加
    if (
        node["refdomain"] == "py"
        and node["reftype"] == "class"
        and node["reftarget"].split(".")[-1] in TARGETS
    ):
        xref = app.env.get_domain("py").resolve_xref(
            env, node["refdoc"], app.builder, "data", node["reftarget"], node, contnode
        )
        xref = typing.cast(reference | None, xref)  # ?
        if not xref:
            raise new Exception("unresolved link to %s", node["reftarget"])  # 変更
        resolved_targets.add(どうにかしてtargetを得る)
        return xref

    assert len(resolved_targets) == len(TARGETS)

[Hiroshiba]

僕達はドキュメントをめったに見ないので、こういうエラーハンドリングをしっかりやっていくのがドキュメントの品質に繋がる･･･のかもなぁとそこそこ強めに思ってます！