Add Changelog build handling for invalid chars

This change adds new handling when building a Changelog file
for specific characters that cause documentation building
warnings/errors to be emitted when sphinx tries to generate
a Changelog html page. The changes include:

- Escaping any '*' in a commit, which sphinx will interpret as the
  start of a new line and throw a warning.
- Escaping any '_' in a commit, which in certain cases, sphinx will
  interpret as an invalid link and create an error.
- Escaping any '`' in a commit, which in certain cases will
  cause sphinx to interpet as a literal, and throw a warning.

After this change, any entries in the changelog that contain
the above "invalid" syntax no longer generate sphinx
warnings/errors and the offending entries now generate correctly.

Change-Id: I672ef4c56486e59a384849a4b182d11129726ae9

3 files changed, 49 insertions, 4 deletions

diff --git a/pbr/git.py b/pbr/git.py
index e334af6..1c70194 100644
--- a/pbr/git.py
+++ b/pbr/git.py
@@ -143,6 +143,27 @@ def get_git_short_sha(git_dir=None):
     return None
 
 
+def _clean_changelog_message(msg):
+    """Cleans any instances of invalid sphinx wording.
+
+    This removes any instances of invalid characters or wording
+    that can be interpreted by sphinx as a warning or error
+    when translating the Changelog into an HTML file for
+    documentation building within projects.
+
+    Currently removes:
+    * Escapes any '_' that sphinx can interpret as a link
+    * Escapes any '*' with sphinx will interpret as a new commit
+
+    """
+
+    msg = msg.replace('*', '\*')
+    msg = msg.replace('_', '\_')
+    msg = msg.replace('`', '\`')
+
+    return msg
+
+
 def _iter_changelog(changelog):
     """Convert a oneline log iterator to formatted strings.
 
@@ -166,6 +187,7 @@ def _iter_changelog(changelog):
         if not msg.startswith("Merge "):
             if msg.endswith("."):
                 msg = msg[:-1]
+            msg = _clean_changelog_message(msg)
             yield current_release, "* %(msg)s\n" % dict(msg=msg)
         first_line = False
 
diff --git a/pbr/tests/test_packaging.py b/pbr/tests/test_packaging.py
index ab8ba49..69a8f79 100644
--- a/pbr/tests/test_packaging.py
+++ b/pbr/tests/test_packaging.py
@@ -270,8 +270,8 @@ class TestPackagingInGitRepoWithCommit(base.BaseTestCase):
 
     def setUp(self):
         super(TestPackagingInGitRepoWithCommit, self).setUp()
-        repo = self.useFixture(TestRepo(self.package_dir))
-        repo.commit()
+        self.repo = self.useFixture(TestRepo(self.package_dir))
+        self.repo.commit()
 
     def test_authors(self):
         self.run_setup('sdist', allow_fail=False)
@@ -287,6 +287,29 @@ class TestPackagingInGitRepoWithCommit(base.BaseTestCase):
         # One commit, something should be in the ChangeLog list
         self.assertNotEqual(body, '')
 
+    def test_changelog_handles_astrisk(self):
+        self.repo.commit(message_content="Allow *.openstack.org to work")
+        self.run_setup('sdist', allow_fail=False)
+        with open(os.path.join(self.package_dir, 'ChangeLog'), 'r') as f:
+            body = f.read()
+        self.assertIn('\*', body)
+
+    def test_changelog_handles_dead_links_in_commit(self):
+        self.repo.commit(message_content="See os_ for to_do about qemu_.")
+        self.run_setup('sdist', allow_fail=False)
+        with open(os.path.join(self.package_dir, 'ChangeLog'), 'r') as f:
+            body = f.read()
+        self.assertIn('os\_', body)
+        self.assertIn('to\_do', body)
+        self.assertIn('qemu\_', body)
+
+    def test_changelog_handles_backticks(self):
+        self.repo.commit(message_content="Allow `openstack.org` to `work")
+        self.run_setup('sdist', allow_fail=False)
+        with open(os.path.join(self.package_dir, 'ChangeLog'), 'r') as f:
+            body = f.read()
+        self.assertIn('\`', body)
+
     def test_manifest_exclude_honoured(self):
         self.run_setup('sdist', allow_fail=False)
         with open(os.path.join(
diff --git a/pbr/tests/test_setup.py b/pbr/tests/test_setup.py
index 0754a8d..5127450 100644
--- a/pbr/tests/test_setup.py
+++ b/pbr/tests/test_setup.py
@@ -165,7 +165,7 @@ class GitLogsTest(base.BaseTestCase):
             self.assertIn("------", changelog_contents)
             self.assertIn("Refactor hooks file", changelog_contents)
             self.assertIn(
-                "Bug fix: create_stack() fails when waiting",
+                "Bug fix: create\_stack() fails when waiting",
                 changelog_contents)
             self.assertNotIn("Refactor hooks file.", changelog_contents)
             self.assertNotIn("182feb3", changelog_contents)
@@ -179,7 +179,7 @@ class GitLogsTest(base.BaseTestCase):
             self.assertNotIn("ev)il", changelog_contents)
             self.assertNotIn("e(vi)l", changelog_contents)
             self.assertNotIn('Merge "', changelog_contents)
-            self.assertNotIn('1_foo.1', changelog_contents)
+            self.assertNotIn('1\_foo.1', changelog_contents)
 
     def test_generate_authors(self):
         author_old = u"Foo Foo <email@foo.com>"