Added code references to search results.

[sarahboyce]

Description

Recently, we added a scroll to text fragment to improve the search result navigation experience.
This takes the first line that was found in the body and scrolls you to this line.

This PR adds references to our Python class/class method/function definitions which will appear as a sub-item of the page search result if they match the search.
This means that when someone searches for "select" they have choice as to what to navigate to. They can chose the "QuerySet.select_related" or "QuerySet.select_for_update". The anchors of these are also robust and so you will navigate to the definition of these (the scroll for text logic is a little fragile due to the html stripping logic of full text search).

This "choice" is even more useful when searching for something like "field":

---

Issues aiming to fix

Ideally this along with the previous highlight text change fixes #1649 and fixes #1734

Review notes

Note that I have added some folks as possible reviewers.
I am not 100% sure the review process given the new website WG but would appreciate feedback as I'd love to land the PR 🫶

This PR has 2 commits, the first commit is a refactor commit to split the test file into multiple test files, the second is the feature.

I originally used regex to full out these code references. @bmispelon rightly pointed out this is brittle. I have since written a custom Sphinx builder in order to use Sphinx's own functionality for getting the python objects.

[alexgmin]

Is there a case in which it makes sense to have the first line of the code reference?
Based on my searches it always seems redundant with the second line

Everything else looks good to me.

[sarahboyce]

Is there a case in which it makes sense to have the first line of the code reference?

It's true that it's duplicate information.
I personally thought reading QuerySet.select_related is nicer than reading django.db.models.query.QuerySet.select_related, but still kept the full path as it's interesting/useful 🤷

[sarahboyce]

I could make it like:

QuerySet.select_related
django.db.models.query

[alexgmin]

It's true that it's duplicate information. I personally thought reading QuerySet.select_related is nicer than reading django.db.models.query.QuerySet.select_related, but still kept the full path as it's interesting/useful 🤷

It is, and I would prefer to keep the short version, but I don't know if there's a case in which the short version is not unique.

I could make it like:

QuerySet.select_related
django.db.models.query

This could also work better than the current one if only the shortened version is not viable due to uniqueness.

[sarahboyce]

It is, and I would prefer to keep the short version, but I don't know if there's a case in which the short version is not unique.

Field for example, django.db.models.fields.Field and django.forms.fields.Field

[bmispelon]

Nice work ✨

In terms of functionality and search experience I think this is a big improvement. I'm worried that the actual implementation might be a bit brittle and could break if sphinx was to change the HTML it outputs (and if it did break, none of our tests would catch it).

But overall this is very good. I've left a few minor comments, nothing major.

[pauloxnet]

I'm sorry, but I haven't found time to review this interesting PR.😞

Could you try explaining in the description what's the goal and the design of this PR. I'm not being pedantic here , but I'm not sure I understood correctly what you want to achieve. 😊

[sarahboyce]

Could you try explaining in the description what's the goal and the design of this PR

Updated the description! Sorry it was lacking a lot of context

I believe this is ready for another round of review ❤️