per feedback from @ejucovy, warn about shadowing gettext with "_"

Author: dcrosta

docs/conf.py

@@ -25,7 +25,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions= ['sphinx.ext.ifconfig', 'sphinx.ext.todo']
+extensions= ['sphinx.ext.ifconfig', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path= ['_templates']
@@ -260,3 +260,7 @@
 #epub_tocdup = True
 
 todo_include_todos=True
+
+intersphinx_mapping={
+'python': ('http://docs.python.org/', None),
+}

docs/writing/style.rst

@@ -37,6 +37,13 @@ will not need that variable, use ``_``:
  filename ='foobar.txt'
  basename, _, ext = filename.rpartition()
 
+.. note::
+
+ "``_``" is commonly used as an alias for the :func:`~gettext.gettext`
+ function. If your application uses (or may someday use) :mod:`gettext`,
+ you may want to avoid using ``_`` for ignored variables, as you may
+ accidentally shadow :func:`~gettext.gettext`.
+
 Create a length-N list of the same thing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~