Function relfn2path_io 

pub fn relfn2path_io(uri: &str, docname: &str, srcdir: &Path) -> PathBuf

The path to actually OPEN for uri written in docname.

Sphinx’s relfn2path calls .resolve() on the joined path (environment/__init__.py:466/:475), so symlinks are followed BEFORE any .. is interpreted. relfn2path instead collapses .. lexically, which under a symlinked directory — docs/examples -> ../../examples and an include of examples/../shared.txt — names a DIFFERENT FILE: sphinx walks up from the link’s target, the lexical rule walks up from the link’s own parent.

The two are separate functions on purpose. §Scope-8 fixes the srcdir-relative spelling every path-bearing surface of included content shows, so relfn2path keeps feeding those; only the read goes through here.