add unreleased_version_title configuration option

Added configuration option ``unreleased_version_title`` with
associated Sphinx directive argument to control whether to show the
computed version number for changes that have not been tagged, or to
show a static title string specified in the option value.

Change-Id: I3069a008451e93cb62e5e43611cf62de5026952f
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/releasenotes/index.rst

@@ -3,6 +3,7 @@
 ===============
 
 .. release-notes:: Unreleased
+   :unreleased-version-title: In Development
 
 .. release-notes:: Mainline
    :branch: origin/master

releasenotes/notes/unreleased-version-title-86751f52745fd3b7.yaml

@@ -0,0 +1,8 @@
+---
+features:
+  - |
+    Added configuration option ``unreleased_version_title`` with
+    associated Sphinx directive argument to control whether to show
+    the computed version number for changes that have not been
+    tagged, or to show a static title string specified in the option
+    value.

reno/config.py

@@ -167,6 +167,13 @@ _OPTIONS = [
         the ``ignore-notes`` parameter to the ``release-notes`` sphinx
         directive.
         """)),
+
+    Opt('unreleased_version_title', '',
+        textwrap.dedent("""\
+        The title to use for any notes that do not appear in a
+        released version. If this option is unset, the development
+        version number is used (for example, ``3.0.0-3``).
+        """)),
 ]
 
 

reno/formatter.py

@@ -42,8 +42,13 @@ def format_report(loader, config, versions_to_include, title=None,
             file_contents[filename] = body
 
     for version in versions_to_include:
-        report.append(version)
+        if '-' in version:
-        report.append('=' * len(version))
+            # This looks like an "unreleased version".
+            title = config.unreleased_version_title or version
+        else:
+            title = version
+        report.append(title)
+        report.append('=' * len(title))
         report.append('')
 
         # Add the preludes.

reno/sphinxext.py

@@ -30,6 +30,9 @@ class ReleaseNotesDirective(rst.Directive):
 
     has_content = True
 
+    # FIXME(dhellmann): We should be able to build this information
+    # from the configuration options so we don't have to edit it
+    # manually when we add new options.
     option_spec = {
         'branch': directives.unchanged,
         'reporoot': directives.unchanged,
@@ -40,6 +43,7 @@ class ReleaseNotesDirective(rst.Directive):
         'earliest-version': directives.unchanged,
         'stop-at-branch-base': directives.flag,
         'ignore-notes': directives.unchanged,
+        'unreleased-version-title': directives.unchanged,
     }
 
     def run(self):
@@ -77,6 +81,10 @@ class ReleaseNotesDirective(rst.Directive):
         if 'earliest-version' in self.options:
             opt_overrides['earliest_version'] = self.options.get(
                 'earliest-version')
+        if 'unreleased-version-title' in self.options:
+            opt_overrides['unreleased_version_title'] = self.options.get(
+                'unreleased-version-title')
+
         if branch:
             opt_overrides['branch'] = branch
         if ignore_notes:

reno/tests/test_formatter.py

@@ -156,3 +156,38 @@ class TestFormatterCustomSections(TestFormatterBase):
         expected = [prelude_pos, api_pos, features_pos]
         actual = list(sorted([prelude_pos, features_pos, api_pos]))
         self.assertEqual(expected, actual)
+
+
+class TestFormatterCustomUnreleaseTitle(TestFormatterBase):
+
+    note_bodies = {
+        'note1': {
+            'prelude': 'This is the prelude.',
+        },
+    }
+
+    scanner_output = {
+        '0.1.0-1': [('note1', 'shaA')],
+    }
+
+    versions = ['0.1.0-1']
+
+    def test_with_title(self):
+        self.c.override(unreleased_version_title='Not Released')
+        result = formatter.format_report(
+            loader=self.ldr,
+            config=self.c,
+            versions_to_include=self.versions,
+            title='This is the title',
+        )
+        self.assertIn('Not Released', result)
+        self.assertNotIn('0.1.0-1', result)
+
+    def test_without_title(self):
+        result = formatter.format_report(
+            loader=self.ldr,
+            config=self.c,
+            versions_to_include=self.versions,
+            title='This is the title',
+        )
+        self.assertIn('0.1.0-1', result)