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

dcrosta · dcrosta · commit 8587cf6a951f · 2012-03-14T16:10:32.000-07:00
diff --git a/docs/conf.py b/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),
+}
diff --git a/docs/writing/style.rst b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
