search

mne-tools / mne-python

MNE: Magnetoencephalography (MEG) and Electroencephalography (EEG) in Python
https://mne.tools
BSD 3-Clause "New" or "Revised" License
2.66k stars 1.31k forks source link

Too many (duplicate) search results in API docs #12589

Open cbrnr opened 4 months ago

cbrnr commented 4 months ago
  1. Go to https://mne.tools/dev/index.html
  2. Click the Search icon in the top bar, enter e.g. "read_raw_edf" in the search box, and hit enter
  3. The first three results are (almost identical): mne.io.read_raw_edf mne.io.read_raw_edf (Python function, in mne.io.read_raw_edf) mne.io.read_raw_edf

Specifically, the link to

I think there should be only one search result pointing to the documentation of that function (the third one). The other two contain anchors, where the first one doesn't have any effect, and the second one scrolls down one line so that the heading is not visible (not useful IMO).

image

drammock commented 4 months ago

This bugs me too but I haven't had time to investigate the cause. Probably related to autodoc?

cbrnr commented 4 months ago

I don't have enough knowledge about Sphinx and related extensions, so I don't even know where to start looking.

drammock commented 4 months ago

the first result (the one where the anchor is all - separated, no .) is the permalink for that heading. generally I think we do want permalinks for headings in our docs, but I wonder if there's a way to disable generating them for the main h1 tag on an API page? It's written by docutils so not sure if it's configurable. The second result (where the anchor has a mix of . and - separators) I'm not sure where that comes from, and I suspect it's actually a bug --- searching for mne.io.read-raw-edf in the generated page source gets no hits so it's not even a valid anchor. My guess is that the latter (invalid) form is "original" and it gets sanitized to the all-dash version by either Sphinx or by the theme, but that sanitization process doesn't remove the old anchor from Sphinx's search index or something.