From 321b3d49cbf67e665e6fdcf6bc7df673e21a1221 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Sun, 28 Jan 2018 18:58:58 +0900
Subject: [PATCH] Fix #3952: apidoc: module header is too escaped

---
 CHANGES                | 1 +
 sphinx/util/rst.py     | 6 ++++--
 tests/test_util_rst.py | 2 ++
 3 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/CHANGES b/CHANGES
index 4782fa141..7c257ccc2 100644
--- a/CHANGES
+++ b/CHANGES
@@ -26,6 +26,7 @@ Bugs fixed
 * #4472: DOCUMENTATION_OPTIONS is not defined
 * #4491: autodoc: prefer _MockImporter over other importers in sys.meta_path
 * #4490: autodoc: type annotation is broken with python 3.7.0a4+
+* #3952: apidoc: module header is too escaped
 
 Testing
 --------
diff --git a/sphinx/util/rst.py b/sphinx/util/rst.py
index 5860b0fd5..a406e0044 100644
--- a/sphinx/util/rst.py
+++ b/sphinx/util/rst.py
@@ -23,13 +23,15 @@ if False:
     # For type annotation
     from typing import Generator  # NOQA
 
-symbols_re = re.compile(r'([!-/:-@\[-`{-~])')
+symbols_re = re.compile(r'([!--/:-@\[-`{-~])')  # symbols without dot(0x2e)
 logger = logging.getLogger(__name__)
 
 
 def escape(text):
     # type: (unicode) -> unicode
-    return symbols_re.sub(r'\\\1', text)  # type: ignore
+    text = symbols_re.sub(r'\\\1', text)  # type: ignore
+    text = re.sub(r'^\.', r'\.', text)  # escape a dot at top
+    return text
 
 
 @contextmanager
diff --git a/tests/test_util_rst.py b/tests/test_util_rst.py
index 406ea710e..07b9174cc 100644
--- a/tests/test_util_rst.py
+++ b/tests/test_util_rst.py
@@ -14,3 +14,5 @@ from sphinx.util.rst import escape
 def test_escape():
     assert escape(':ref:`id`') == r'\:ref\:\`id\`'
     assert escape('footnote [#]_') == r'footnote \[\#\]\_'
+    assert escape('sphinx.application') == r'sphinx.application'
+    assert escape('.. toctree::') == r'\.. toctree\:\:'