[singlehtml] toctree no filename with anchor

[gastmaier]

Purpose

Fix toctree links to page anchor in the singlehtml output.
Only matters for themes that include the right sidebar in the singlehtml page, but particularly useful for using the singlehtml to then generate a pdf (since the toctree allows fine tuning the depth of the table of contents).

On #11970, same-document links dropped the uri (filename part). On #12551, fixes to do not include the filename on hyperlinks was added. So an anchor for a:

• doc reference: #document-my-page
• ref reference: #my-anchor.

On #13037, fix_refuris was removed, which would blindly rmatch #.*
However, #12551 missed the toctree constructor, which was still generating:

• #document-my-page#my-anchor

Modify _resolve_toctree() to do not include rel_uri if the is an anchorname.

Tests failing

These two tests are failing, from the immediate previous commit:

FAILED tests/test_builders/test_build_epub.py::test_nested_toc - AssertionError: assert ('navPoint5',...o-1', 'foo.1') == ('navPoint5',...o-1', 'foo.1')
FAILED tests/test_builders/test_build_epub.py::test_escaped_toc - AssertionError: assert ('navPoint5',...1', 'foo “1”') == ('navPoint5',...1', 'foo “1”')

It may be necessary to make the code specific to when the builder is singlehtml.

References

• 🐛 Fix singlehtml target uris to be same-document references #11970,
• singlehtml: Use same-document hyperlinks for internal project references #12551
• singlehtml: deprecate the 'fix_refuris' helper function #13037

[gastmaier]

Changed the approach to only affect singlehtml.
since the original approach would break toctrees that include anchor and are multi file (e.g. html):

toctree_html = context["toctree"](
    collapse=False,
    titles_only=False,
    maxdepth=-1,
    includehidden=True,
)

It may be worth considering that after all, having the filename in the anchor #document-<filename>, may be more consistent with other single file builders (epub, ...?)

pinging @jayaddison for insight

[AA-Turner]

@gastmaier sorry for the delay in initial review. Please could you add a CHANGES entry and a test? Hopefully one of us will have time for a detailed review in the near future.

A

[gastmaier]

My issue with my solution is that it doesn't resolve the cross-doc id collision, since id collision is resolved only per doc and not across doc.
The LaTeX builder solves it by having the sphinx/writers/latex.py#hypertarget[withdoc=True] method, where is suffixes the docutils id with the docname.
I believe doing the same for singlehtml would be better,
so a #id1 anchor becomes #document-path/to/doc/index#id1 (1)
but I am struggling to implement, at the writers/html5 stage.

Maybe it just needs its own spin of hypertarget at the exact locations as the latex writer, but I will revisit it later.

(1) These are valid HTML anchors, but but require escaping when manipulating with:
css

#document-test\/extra\#test {color: #f00;}

and javascript

document.querySelector('#document-test\\/extra\\#test')

[jayaddison]

Sorry, I was away on holiday and am catching up on notifications currently. I like the objective of this changeset and will find some time to review #13739 during the next few days.