sphinx-doc / sphinx-doc/sphinx
shortanchor compression is lossy
Open
Nobody has claimed this yet.
html search
type:bug
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
When the Sphinx search module encodes the search index, it uses a compression scheme for anchor names. Unfortunately this compression scheme:
Unfortunately this compression scheme is lossy for a few reasons:
- The compression is based on comparing the HTML-escaped
fullnameto the anchor name. However, thefullnameis never stored in the search index, only thedispname. The JavaScript search implementation therefore has to decode the anchor name based on thedispname, rather than thefullname, and if they differ then this would lead to the wrong result. For some domains, like Python, thedispnameis always equal to thefullname, but for other domains, likestd, that is not always the case. - The compression uses the special values of
""and"-"to encode compressed values. However, that means that it cannot encode an actual anchor equal to""or"-". For example, I have some Sphinx customizations that use a separate page for each object, and therefore have an empty string as the anchor name.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at sphinx/search/init.py around the linked compression code, then trace the JavaScript search decoding that consumes the index. Reproduce cases where dispname differs from fullname and where the anchor is empty or "-", and verify that the revised encoding and decoding preserve each anchor.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, python
- Domain
- search
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100