[1.11.x] Fixed docs build with Sphinx 1.6.

Backport of f370bfb108 from master

docs/Makefile

@@ -9,10 +9,14 @@ PAPER         ?=
 BUILDDIR      ?= _build
 LANGUAGE      ?=
 
+# Convert something like "en_US" to "en", because Sphinx does not recognize
+# underscores. Country codes should be passed using a dash, e.g. "pt-BR".
+LANGUAGEOPT = $(firstword $(subst _, ,$(LANGUAGE)))
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees -D language=$(LANGUAGE) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees -D language=$(LANGUAGEOPT) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

docs/_ext/djangodocs.py

@@ -13,7 +13,10 @@ from sphinx.domains.std import Cmdoption
 from sphinx.util.compat import Directive
 from sphinx.util.console import bold
 from sphinx.util.nodes import set_source_info
-from sphinx.writers.html import SmartyPantsHTMLTranslator
+try:
+    from sphinx.writers.html import SmartyPantsHTMLTranslator as HTMLTranslator
+except ImportError:  # Sphinx 1.6+
+    from sphinx.writers.html import HTMLTranslator
 
 # RE for option descriptions without a '--' prefix
 simple_option_desc_re = re.compile(
@@ -226,7 +229,7 @@ class VersionDirective(Directive):
         return ret
 
 
-class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
+class DjangoHTMLTranslator(HTMLTranslator):
     """
     Django-specific reST to HTML tweaks.
     """
@@ -287,7 +290,7 @@ class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
         old_ids = node.get('ids', [])
         node['ids'] = ['s-' + i for i in old_ids]
         node['ids'].extend(old_ids)
-        SmartyPantsHTMLTranslator.visit_section(self, node)
+        HTMLTranslator.visit_section(self, node)
         node['ids'] = old_ids
 
 

docs/conf.py

@@ -52,6 +52,8 @@ extensions = [
 # Add it only if spelling check is requested so docs can be generated without it.
 if 'spelling' in sys.argv:
     extensions.append("sphinxcontrib.spelling")
+    # Workaround for https://bitbucket.org/dhellmann/sphinxcontrib-spelling/issues/13
+    html_use_smartypants = False
 
 # Spelling language.
 spelling_lang = 'en_US'
@@ -188,10 +190,6 @@ html_theme_path = ["_theme"]
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-html_use_smartypants = True
-
 # Content template for the index page.
 # html_index = ''