Distinguish name of extension, name of sample target file and name of…

[jd41]

… sample target section

I think the documentation is somewhat clearer if the role, the example target file and the example target section aren't all named "hoverxref". I am a Sphinx/RST beginner, currently hunting down why my hoverxref example doesn't work. Having made these changes, I can confirm that having a section "hoverxref_section" within a file "hoverxref_file" should be enough to create a findable target "hoverxref_file:hoverxref_section". It was less clear before. A new user can now easily confirm this by grepping for "hoverxref_section".

Update: Sorry, I mixed up some words in the commit message description! Please refer to this PR description.

[jd41]

I actually disagree that "Title" looks worse than "hoverxref". What about "example_file.rst", "Example section title", and "example_label"? The important thing is just that they are all different and unique (i.e. these terms don't appear anywhere else in a relevant source code) - if we spend more time discussing them, I'm gonna call bikeshedding =)

I propose "example_label" because the result of my debugging two months ago was that I hadn't understood the need to use the autosectionlabel extension so that the section titles automatically get turned into labels. I think that using this extension in the hoverxref example is a tripwire for a new user as well, so I'd also consider manually labeling the target section here instead. Then the documentation gets closer to a minimal working example of hoverxref. Alternatively, one could point out the usage of autosectionlabel explicitly.

Update: I forgot that after including autosectionlabel, I still had to figure out that I also need to set autosectionlabel_prefix_document = True to get this label style to work. So that's another small tripwire.

[jd41]

Hi! Sorry, I didn't understand I should have clicked on "re-request review".

Would you like to decide on how to call them for now, and merge that thing? I feel that either the current PR or your suggestion or my suggestion in the last message improves on the status quo. If an even better solution is possible, of course I won't object if you change something again soon =)