fix: preserve symlink for include directive in relfn2path

[aryansk]

Fixes #14520

Problem

Within doc/index.rst, we are including a doc/README.rst file, which is actually a symlink to the same file in the root directory. This layout works well until Sphinx 7, but starts failing on Sphinx 8 when running with -W: doc/README.rst: WARNING: document isn't included in any toctree [toc.not_included].

Demo: https://github.com/tech-writing/sphinx-symlink-regression — doc/README.rst -> ../README.rst with .. include:: README.rst in doc/index.rst.

Change

• In sphinx/environment/__init__.py:relfn2path — change Path(...).resolve() to Path(os.path.normpath(...)) (via Path(...).absolute() + os.path.normpath) so abs_fn stays as doc/README.rst (the symlink path inside srcdir) rather than resolving to ../README.rst outside srcdir. This preserves rel_fn as README.rst and note_included correctly maps to the README docname found via discover (which finds README.rst in doc as a file).

Keep unrelated cleanup out of this PR.

Why this approach

Sphinx 8 changed relfn2path to use Path.resolve() which follows symlinks. For doc/README.rst -> ../README.rst, resolve() makes abs_fn the target outside srcdir, so _relative_path becomes ../README.rst and path2doc fails to map to README. Using normpath without resolving keeps the symlink path inside srcdir, matching discover's README docname and fixing toc.not_included.

Testing

command: cd /tmp/sphinx-symlink-demo/doc && uv run --with='sphinx==7.*' sphinx-build -b html . _build7 -W
result: build succeeded (0 warnings)

command: cd /tmp/sphinx-symlink-demo/doc && uv run --with='sphinx==8.*' sphinx-build -b html . _build8 -W
result: 1 warning [toc.not_included] (repro)

command: PYTHONPATH=/tmp/sphinx-14520/repo uv run --with='sphinx==8.*' python -m sphinx -b html /tmp/sphinx-symlink-demo/doc /tmp/sphinx-14520/_build_test -W
result: build succeeded (0 warnings) with patched relfn2path

command: git diff --check
result: clean

Documentation and release impact

• User-facing behavior fixed (include directive with symlinked README)
• Changelog/release note needed: bug fix
• Migration or compatibility note needed
• No documentation impact

Review notes

• Known limitations: none beyond symlink include
• Follow-up issue, if any: none
• Security/licensing considerations: none