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

Created on 2010-06-14 15:09 by eric.araujo, last changed 2010-06-20 16:40 by techtonik.

Messages (4)
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.
History
Date User Action Args
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