GH-101100: Resolve reference warnings in library/stdtypes.rst #138420
Conversation
AA-Turner
added
needs backport to 3.13
bedevere-app
bot
added
awaiting core review
docs
AA-Turner
changed the title
|
I think that the right fix for this is to add anchors instead of removing references. |
|
@serhiy-storchaka I've generally been hesitant to suppress cross-references, but I think all the instances here make sense, given their context. Are there some specific ones you would revert? A |
| another set. The :class:`frozenset` type is immutable and :term:`hashable` --- | ||
| its contents cannot be altered after it is created; it can therefore be used as | ||
| a dictionary key or as an element of another set. | ||
| like :meth:`add <frozenset.add>` and :meth:`remove <frozenset.add>`. |
There was a problem hiding this comment.
There is no frozenset.add().
There was a problem hiding this comment.
Because set and frozenset are documented together, there is no cross-reference target for set.add, it is labelled as frozenset.add instead. This link goes to the correct place.
There was a problem hiding this comment.
But this is a wrong name for anchor. We should do something with this.
There was a problem hiding this comment.
I agree. I plan to fix it, but it requires changes (& a release) of Sphinx. This PR makes the reference link to the right place, and more importantly means that no future reference errors can be introduced into stdtypes.rst.
Once it is fixed, I plan to go back and update here & a few other places where we have used a different target to the intended one.
There was a problem hiding this comment.
Now, I think that we should reorganize the set/frozenset documentation in the way similar to the sequence or bytes/bytearray documentation.
- Dedent method descriptions and add class name prefixes. E.g.:
.. method:: frozenset.isdisjoint(other, /) set.isdisjoint(other, /)
- Move operators to separate tables. This may wait.
All of them? See my suggestion #101100 (comment) . After implementing it the references in footnotes will gone, as they will become the part of the method description, and many other references will became working. After that we can check what remains. |
|
See #138474, putting this in draft for now. A |
# Conflicts: # Doc/library/stdtypes.rst
|
(Resolved conflict) |
|
Thanks @AA-Turner for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14. |
…ythonGH-138420) (cherry picked from commit cde19e5) Co-authored-by: Adam Turner <[email protected]>
|
GH-141855 is a backport of this pull request to the 3.14 branch. |
|
Sorry, @AA-Turner, I could not cleanly backport this to |
…H-138420) (#141855) Co-authored-by: Adam Turner <[email protected]>
| another set. The :class:`frozenset` type is immutable and :term:`hashable` --- | ||
| its contents cannot be altered after it is created; it can therefore be used as | ||
| a dictionary key or as an element of another set. | ||
| like :meth:`add <frozenset.add>` and :meth:`remove <frozenset.add>`. |
There was a problem hiding this comment.
Wrong reverence to remove().
4 participants
📚 Documentation preview 📚: https://cpython-previews--138420.org.readthedocs.build/