[RFE] Support union types specification using | (vertical bar/pipe)

[radekholy24]

Please add a support for specifying multiple types acceptable for a parameter/attribute/variable.
Use case:
Imagine that there is a function that accepts both bytes and str. The docstring would look like:

def foo(text):
    """Bar

    :param text: a text
    :type text: bytes | str

    """

Such a syntax is already supported by e.g. PyCharm.

[zopieux]

From the docs:

Multiple types in a type field will be linked automatically if separated by the word “or”:

So this feature is already available using this syntax:

def foo(foo):
    """
    Bla blu

    :type foo: str or int or None
    """

Instead of multiplying the possible syntaxes for this, why don't we try to adhere to PEP 484 and the typing module? These are already Python standards that are readily available in modern Python releases. I wouldn't take PyCharm as a reference for this kind of stuff, as they seem to enjoy never following the community's common practices.

def foo(foo):
    """
    Bla blu

    :type foo: Union[str, int, None]
    """

[radekholy24]

A lot of time has passed since I filed this issue. I don't remember whether I specifically wanted the pipe syntax or whether it was just an example... I certainly didn't know about that PEP and that module didn't exist at that time as far as I know... As well as the paragraph in the documentation that you have mentioned... And that PyCharm's syntax was, for sure, the only syntax I knew... Maybe it was a mistake to suggest a particular implementation...

Now, it's enough for me that there is a support for union types in Sphinx already...

[ErikBjare]

The pipe syntax is now in the standards-track PEP 604.

I'm personally less interested in sphinx supporting type specification using pipes, but more so about the type annotations in the output using the pipe notation, saving the space taken by writing out the often-verbose Union, such that this:

would become this:

[tk0miya]

@ErikBjare Please check the latest Sphinx out with Python-3.10. The union types using pipes are displayed as-is.