classification
Title: Add a default role to allow writing bare `len` instead of :func:`len`
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, docs@python, eric.araujo, ezio.melotti, georg.brandl, techtonik
Priority: normal Keywords:

Created on 2010-06-14 15:09 by eric.araujo, last changed 2012-10-27 18:18 by eric.araujo. This issue is now closed.

Messages (8)
msg107790 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-06-14 15:09
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?
msg107795 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-06-14 15:56
The type doesn't matter anyway, no need to find it by questionable means.
msg108223 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-06-20 04:29
-1 I like how explicit it is now.
msg108238 - (view) Author: anatoly techtonik (techtonik) Date: 2010-06-20 16:40
`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.
msg164690 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-07-05 18:49
> 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?
msg170695 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-19 01:49
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).
msg173936 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-10-27 16:34
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
msg173948 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-10-27 17:32
I'm not very attached to it, so I'm fine with closing.
History
Date User Action Args
2012-10-27 18:18:27eric.araujosetstatus: open -> closed
resolution: rejected
stage: resolved
2012-10-27 17:32:52georg.brandlsetmessages: + msg173948
2012-10-27 16:34:31eric.araujosetmessages: + msg173936
2012-09-19 01:49:18ezio.melottisetmessages: + msg170695
2012-07-05 18:49:20eric.araujosetmessages: + msg164690
2012-05-15 07:03:11ezio.melottisetnosy: + ezio.melotti
2010-06-20 16:40:17techtoniksetnosy: + techtonik
messages: + msg108238
2010-06-20 04:30:01benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg108223
2010-06-14 15:56:54georg.brandlsetnosy: + georg.brandl
messages: + msg107795
2010-06-14 15:09:10eric.araujocreate