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
documentation of '%r' links to the wrong repr #61861
Comments
The documentation of '%r' in http://docs.python.org/2/library/stdtypes.html#string-formatting-operations links to the wrong repr, the module (http://docs.python.org/2/library/repr.html#module-repr) instead of the builtin function (http://docs.python.org/2/library/functions.html#func-repr). |
Thanks for catching this; Sphinx’ lookup is confusing sometimes. Using |
It just highlights the mistake we made calling a builtin module the same name as a builtin function :) |
Adding a '.' to the beginning (i.e. "If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python’s codecs module, :py:func:`open` always refers to the built-in function, while :py:func:`.open` refers to codecs.open()." I'm not sure what other options I can try after looking at the reST documentation. It seems like our best bet would be if we could define a priority for same-name functions when two definitions are discovered. I didn't see a way to do this in Sphinx/reST so I'm not sure how to move forward with this. I'm assuming we don't want to link directly to the correct url if it can be avoided. Also, I noticed http://docs.python.org/2/library/repr.html#module-repr links to the wrong repr() a few times where it mentions the "built-in" function. |
But shouldn't the highlighting be handled by Pygments? |
You can always use a ref role instead of func. func tries to find a module, class or function in the global Sphinx index, but ref lets you link to one specific target (see the table at the top of library/functions.rst for an example). |
Ah that's the type of thing I was looking for, thanks Éric. I saw the underscored reference in functions.rst last night but figured it was just a local file link. I'll have a patch available later today. Thanks again. |
So the :ref: keyword helps and creates a link, but it has the unfortunate side effect of adding different markup and style. I've attached two images to illustrate the differences. I couldn't find a way in the Sphinx or reST documentation to force it to style like a :func:, and my searches didn't come up with much either. Does anyone know of a way to style a :ref: just like a :func:? The code I used to create the fixed link is: :ref:`repr() <func-repr>` |
I don't think the style is so important, especially since this issue only affects 2.7. |
Reproduced the issue and generated a patch following Kyle's documented approach. Please note that this patch addresses the link problem, but does not address the style issue. Thanks. |
Fixed, thanks. |
New changeset dd5e7aef4d5b by Georg Brandl in branch '2.7': |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: