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

diff --git a/docs/conf.py b/docs/conf.py
index 7aa0223..ad90eb2 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,7 +25,7 @@ sys.path.append(os.path.abspath('_themes'))
 
 # 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_copyright = u'2010, Kenneth Reitz'
 #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
index ada5d3c..666ac6c 100644 (file)
--- 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~