[Python-Dev] [Python-checkins] cpython: Issue #15502: Finish bringing importlib.abc in line with the current

[Chris Jerdonek]

On Fri, Aug 10, 2012 at 9:21 AM, brett.cannon
<python-checkins at python.org> wrote:
> http://hg.python.org/cpython/rev/0a75ce232f56
> changeset:   78485:0a75ce232f56
> user:        Brett Cannon <brett at python.org>
> date:        Fri Aug 10 12:21:12 2012 -0400
> summary:
>   Issue #15502: Finish bringing importlib.abc in line with the current

> +      cache used by the finder. Used by :func:`invalidate_caches()` when

Minor style nit: the Dev Guide says not to include the trailing
parentheses in :func: text:

"func: The name of a Python function; dotted names may be used. The
role text should not include trailing parentheses to enhance
readability..."

(from http://hg.python.org/devguide/file/f518f23d06d5/documenting.rst#l888 )

(though I don't know why the Dev Guide says the opposite for :c:func:
and is silent on :meth:.)

On a related note: this may not be common knowledge, but it is
possible to hyperlink to a function definition while still showing
different text (in particular passed arguments) by using the following
Sphinx syntax:

  :func:`locale.getpreferredencoding(False) <locale.getpreferredencoding>`

This is in the Dev Guide, but I haven't seen the construct used in
many places where it seems like it would be helpful and appropriate.

--Chris