Docs: In param lists mark up multiple types correctly

[erlend-aasland]

Use the word 'or' instead of the symbol '|'.

See also the Sphinx docs:

• https://www.sphinx-doc.org/en/master/usage/domains/python.html#send_message

---

📚 Documentation preview 📚: https://cpython-previews--116389.org.readthedocs.build/

[AlexWaygood]

My first reaction was "but these aren't valid Python type hints anymore!"

My second reaction was to go... "Wait, he's right, these are probably much more readable for casual readers of the documentation who might not be familiar with Python's typing system" :)

[AlexWaygood]

Is this one still perhaps a bit too complex for the docs? Not sure how it could be simplified, though

[erlend-aasland]

It is definitely complex. In this case, I'd say readability is definitely improved using or iso. |.

[hugovk]

I checked the first one:

Before	After

Both are linked and marked up the same. Are there some instances where there's a difference (other than "|" vs. "or")?

Should we be formatting None as None? https://devguide.python.org/documentation/markup/#quick-reference

[erlend-aasland]

Both are linked and marked up the same. Are there some instances where there's a difference (other than "|" vs. "or")?

@hugovk: indeed, it looks like they are all the same. I also tried just using a comma (:type name: str, dict), which is also marked up like this. Looks like it just boils down to a style issue. Do we want it written as str or dict, or str | dict? See also @AlexWaygood's comment: #116389 (comment).

[hugovk]

No strong preference either way.

In theory, if Sphinx says to do it one way, it makes sense to do that. In practice, if it makes no difference, let's pick the one we prefer. So I'll leave it up to you ;)

[erlend-aasland]

In theory, if Sphinx says to do it one way, it makes sense to do that. In practice, if it makes no difference, let's pick the one we prefer. So I'll leave it up to you ;)

It's a minor style issue to decide on, nevertheless it feels wrong for me to decide on the convention in a PR. I think at least a heads-up in the Documentation category on Discourse would be nice :)

UPDATE: I created a topic on Discourse.

[erlend-aasland]

Marked as draft until a decision has been made.

[picnixz]

In theory, if Sphinx says to do it one way, it makes sense to do that

Well... I don't remember whether there are corner cases where we fail to render correctly the docs (I know that there is an open issue in Sphinx about something related and I know it's something I've replied to but I don't remember the issue :D).

Personally, I tend to use | for the sole reason that it's shorter on the docs side. However, using "or" may be clearer for users in general because some of your types might have "|" inside them, e.g., list[int | str] | str and you need a bit more effort to detect which | is the one actually separating the two types.

For CPython, I'd say that using or is fine and possibly preferrable for end-users and beginners.

[erlend-aasland]

We discussed this at the docs meet-up recently, and there was many of arguments in favour of or. We landed on that we'll create an issue on the EB repo and let them decide.

[erlend-aasland]

Based on python/editorial-board#7 (comment), I suspect the EB is ok with this PR. If so, let's land this and follow up with a devguide PR, to document this recommended practise.

[erlend-aasland]

Take a look at the CI failure for commit d464f3f. It seems like Sphinx do not support its own convention for attributes. If this is really the case, we should definitely not land this PR, and instead recommend continued use of |, or to fix Sphinx.

cc. Sphinx wizard @AA-Turner 🪄

[picnixz]

Huh, maybe it requires Napoleon's extension for that to work? I don't remember where we parse the or or |.

[electric-coder]

@erlend-aasland basically what you're asking for is an historical disambiguation (initially motivated by a syntactic error in this PR) that can't be arbitrated by Sphinx devs alone because the acceptable values in those fields are multi-language and predate PEP 484 type expressions as we know them.

The closest things is the napoleon extension intro on docstrings and a comprehensive historical rewrite to bring it up to date has not yet been proposed. Also, the specific numpy docstring style syntax is sufficiently ambiguous/underspecified (you'll rarely find full explanations of default values in APIs - or a complete example in their docs) and more or less independent.

Every beginner who ever tried to write a docstring fell into this problem, but it's an extremely hard document to write because even the use of prose like types (int or str) is kind of an historical artifact that lacks an authoritative document to explain it (I've commented on the Sphinx repo it would take an archeologist), be that in the Sphinx docs, the PEPs, or numpydoc.

[erlend-aasland]

The EB landed on preferring | iso. or. Closing this long-lived PR.