Skip to content
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

Drop special cross reference helper for exceptions, functions and methods #7246

tk0miya opened this issue Mar 3, 2020 · 2 comments


Copy link

tk0miya commented Mar 3, 2020

Is your feature request related to a problem? Please describe.

So far, :py:exc: role automatically searches exception classes under exceptions module. But, since python3, exception classes has been moved into builtins module. So this fallback works fine only for python2 docs.

.. py:exception:: exceptions.Exception

:py:exc:`Exception` can refer `exceptions.Exception` automatically even if no ``py:module::`` given.

In addition, this fallback is a part of python domain, not intersphinx. So it only works for a document contains descriptions for standard exceptions. It does not work for a document only refers python standard exceptions.

Side note: python domain also has another special support for :py:func: and :py:meth:. It also automatically searches functions and methods under object.

.. py:method:: object.__str__()

:py:func:`__str__` and `:py:meth:`__str__` can refer `object.__str__()` automatically even if no ``py:class:`` given.

I don't know why python domain searches them on object.* namespace. I can understand if it searches under builtins module. Anyway, this is also meaningless.

Describe the solution you'd like
Drop these special treatment from python domain.

Describe alternatives you've considered

Additional context

Copy link

+1 to drop special cross reference helper

Copy link
Member Author

tk0miya commented Mar 7, 2020

Note: python-docs declares exceptions classes as root item (not under builtins package):

$ python -m sphinx.ext.intersphinx
    ArithmeticError                          library/exceptions.html#ArithmeticError
    AssertionError                           library/exceptions.html#AssertionError
    AttributeError                           library/exceptions.html#AttributeError
    BaseException                            library/exceptions.html#BaseException
    BlockingIOError                          library/exceptions.html#BlockingIOError
    BrokenPipeError                          library/exceptions.html#BrokenPipeError
    BufferError                              library/exceptions.html#BufferError
    BytesWarning                             library/exceptions.html#BytesWarning
    ChildProcessError                        library/exceptions.html#ChildProcessError
    ConnectionAbortedError                   library/exceptions.html#ConnectionAbortedError
    ConnectionError                          library/exceptions.html#ConnectionError
    ConnectionRefusedError                   library/exceptions.html#ConnectionRefusedError
    ConnectionResetError                     library/exceptions.html#ConnectionResetError
    DeprecationWarning                       library/exceptions.html#DeprecationWarning
    EOFError                                 library/exceptions.html#EOFError
    EnvironmentError                         library/exceptions.html#EnvironmentError
    Exception                                library/exceptions.html#Exception

tk0miya added a commit to tk0miya/sphinx that referenced this issue Mar 7, 2020
@tk0miya tk0miya closed this as completed in 8e1934b Mar 8, 2020
tk0miya added a commit that referenced this issue Mar 8, 2020
Close #7246: Drop special cross reference helper for exceptions, functions and methods
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 27, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
None yet

No branches or pull requests

2 participants