-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Intersphinx cannot link to section headers with uppercase names #12008
Comments
For reference:
I'm not really sure what you're proposing here? That Sphinx should internally postpone the normalization step to process |
I don't know what
which describes the attribute at https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.dirhtml.DirectoryHTMLBuilder.format (note the uppercase anchor name). Just for section headers in particular, Sphinx happens to "sluggify" them to lowercase names, and that's how they get written to the inventory. There's nothing in particular that specifies that choice of sluggification method, and other systems (like Documenter) have a different sluggification that preservers case. There is no "normalization" happening when writing inventories. Sphinx chooses to "normalize" e.g., sphinx/sphinx/ext/intersphinx.py Lines 334 to 352 in 8aa5edd
(line 336). What I'm saying is that the normalization needs to happen in both places: the So you either normalize the keys in I'd be happy to do an alternative PR to modify
I'm not sure what you mean. But no, |
Before anything, I want to understand why the One reason that I can think of is because of labels that are auto-generated for sections with |
Before that: Before that (f82a4a4):
Ultimately, it comes down to
See also https://mail.python.org/pipermail/python-checkins/2008-July.txt
At that point, we're entering the pre-git era, so I don't think I can track this much further. The https://svn.python.org/projects/doctools/ site is still around if someone wants to dig deeper. I'm pretty sure all of this predates any serious Intersphinx capabilities, definitely the It's perfectly fine for label names in references to be case-insensitive
But label names in inventory files that don't originate from |
Maybe I should clarify the core of the issue more concisely, since it's quite narrow and specific to
|
Thank you for your very precise investigation (I didn't ask for that much actually). Personally, I prefer not changing anything on the inventory side and fix the thing on the resolver side instead as you said:
Maybe we will change that later again if there are still issues. |
That’s fine! I’ll make a second PR for that within the next couple of day. |
Look up `:std:label:` object types case-insensitively in an intersphinx inventory. This is needed because `ref` and `numref` references (which both resolve to `:std:label:`) are case insensitive. They lowercase their target under the assumption that the target name in any inventory file is also lowercased. That assumption holds for labels in inventory files generated by Sphinx from `.rst` files, since it generates lowercase labels. However, other documentation generators (such as the Julia Documenter.jl, which also writes `objects.inv` inventory files as of version 1.3) use mixed-case labels for section title. With the change in this commit, if the lowercase label cannot be found in the inventory, also try a case-insensitive match. See sphinx-doc#12008
OK, opened the alternative PR #12033 I agree that this is a better solution, as the problem is really the same one as was resolved earlier for |
Look up `:std:label:` object types case-insensitively in an intersphinx inventory. This is needed because `ref` and `numref` references (which both resolve to `:std:label:`) are case insensitive. They lowercase their target under the assumption that the target name in any inventory file is also lowercased. That assumption holds for labels in inventory files generated by Sphinx from `.rst` files, since it generates lowercase labels. However, other documentation generators (such as the Julia Documenter.jl, which also writes `objects.inv` inventory files as of version 1.3) use mixed-case labels for section title. With the change in this commit, if the lowercase label cannot be found in the inventory, also try a case-insensitive match. See sphinx-doc#12008
Describe the bug
In
sphinx/sphinx/domains/std/__init__.py
Lines 544 to 548 in 8aa5edd
it is specified that
:ref:
and:numref:
references should lowercase the name of the target before resolving the link. When combined withintersphinx
, this makes an implicit assumption that any "name" for astd:label
entry in a loaded inventory is lowercase. Typically, the name corresponds to the HTML-anchor of the section header. Since Sphinx generates lowercase anchors by default, this assumption holds. However, other documentation generators may not choose lowercase anchors. For example, Documenter.jl currently uses capitalization in anchors for section titles, and also writes anobjects.inv
file with names matching those anchors.It would be unreasonable to require that all inventory files may only contain lowercase names: since the inventory format specifies
there is a strong incentive for the
name
to match the anchor. In the case ofDocumenter
-generated inventory files, deviating from this would significantly increase the size of the inventory file.The correct behavior would be for Sphinx to normalize the names of
std:label
to lowercase when reading in theobjects.inv
file, simply by addingbefore line 141 in
sphinx/util/inventory.py
How to Reproduce
See the MWE at
sphinx-to-documenter-links
.The problematic inventory file is, e.g., http://juliadocs.org/DocumenterInterLinks.jl/stable/objecs.inv from the
DocumenterInterLinks
project.The problem is demonstrated in the following line in
docs/source/index.rst
:Environment Information
Sphinx extensions
Not relevant, since the issue is with
std:label
, not objects in thejl
domain, but technicallyjulia_domain.py
Additional context
#8982 seems related
The text was updated successfully, but these errors were encountered: