[issue8996] Add a default role to allow writing bare `len` instead of :func:`len`
New submission from Éric Araujo merwok@netwok.org:
Following a discussion on IRC:
<birkenfeld> I would even prefer having more of just `object` instead of :func:`object` or :class:`object`
I think it would be feasible to write a reST role that would use inspect or pydoc to find the type. It would not violate “In the face of ambiguity, refuse the temptation to guess” if it only resolves `somebuiltin` and `some.fully.qualified.name`.
Cons: People unfamiliar with reST might confuse ``code`` with `name`; interpreting the role may prove non-trivial (either requiring importing Python module to introspect them, or keeping a mapping of names→types in some file).
Thoughts?
---------- assignee: docs@python components: Documentation messages: 107790 nosy: docs@python, merwok priority: normal severity: normal status: open title: Add a default role to allow writing bare `len` instead of :func:`len` type: feature request
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Georg Brandl georg@python.org added the comment:
The type doesn't matter anyway, no need to find it by questionable means.
---------- nosy: +georg.brandl
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Benjamin Peterson benjamin@python.org added the comment:
-1 I like how explicit it is now.
---------- nosy: +benjamin.peterson
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
anatoly techtonik techtonik@gmail.com added the comment:
`someref` would be more convenient than :func:`someref` but in case of namespace conflict (for example, as a result of documentation merge it both :func:`someref` and :class:`someref` can appear) - it would be necessary to go through all the links in both sources and update ambiguous references to point to the right type.
But perhaps the biggest problem would be to explain users what happens. Also in the case when you create new :class:`someref` and Sphinx detects conflict.
---------- nosy: +techtonik
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Changes by Ezio Melotti ezio.melotti@gmail.com:
---------- nosy: +ezio.melotti
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
for example, as a result of documentation merge it both :func:`someref` and :class:`someref` can appear
I think this would cause a warning from Sphinx, as all class/meth/func/mod/etc roles look up in the same namespace (what Georg said).
Benjamin is -1 for explicitness I am -0 because of the ` vs. `` possible ambiguity—I prefer disabling the default role altogether Georg, are you still +1 or should we reject this?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Ezio Melotti added the comment:
I think I'm -1 on this, for the following reasons: * it's less explicit; * it gives you less control (I'm thinking e.g. at the () added by :func:/:meth: but not :class:, so that :func:`int` and :class:`int` are rendered in different ways); * even though this might have been OK if we used it from the beginning, now we are using specific roles everywhere, and changing them will either result in a mass update or in a mixed style -- none of which are desirable; * if the mass update is done and later on we change our mind, it's difficult to switch back from `...` to :role:`...`.
Disabling `...` sounds OK to me (I don't think we have many left, if any).
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Éric Araujo added the comment:
Unless Georg would still like this, I retract the proposal.
Ezio:
Disabling `...` sounds OK to me (I don't think we have many left, if any).
I think some of them crept up in logging and unittest docs, but they are easy to find with Doc/tools/rst-lint.py
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Georg Brandl added the comment:
I'm not very attached to it, so I'm fine with closing.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
Changes by Éric Araujo merwok@netwok.org:
---------- resolution: -> rejected stage: -> committed/rejected status: open -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue8996 _______________________________________
participants (5)
-
anatoly techtonik -
Benjamin Peterson
-
Ezio Melotti
-
Georg Brandl
-
Éric Araujo