Add release highlights

This adds the ability to provide release highlights in the deliverable
yaml file. These highlights can then be extracted and displayed into
published documentation using a new 'cycle-highlights' directive.

Change-Id: I40791dad4b5a4d2c4089e5e43d52f00b52cc3217

README.rst

@@ -315,6 +315,9 @@ that deliverable. For each deliverable, we need to track:
   * the version number to use
 
 * highlights for the release notes email (optional)
+* cycle highlights that will be published to
+  ``releases.openstack.org/$SERIES/highlights.html`` (optional, and for
+  cycle_with_intermediary amd cycle_with_milestone projects only)
 * the starting points of all branches
 
     We track this metadata for the history of all releases of the
@@ -370,7 +373,7 @@ The top level of a deliverable file is a mapping with keys:
 
 ``artifact-link-mode``
   Describe how to link to artifacts produced by the project. The
-  default is ``tarball`. Valid values are:
+  default is ``tarball``. Valid values are:
 
   tarball
     Automatically generates links to version-specific files on
@@ -380,8 +383,8 @@ The top level of a deliverable file is a mapping with keys:
     Do not link to anything, just show the version number.
 
 ``repository-settings``
-  Mapping of special settings to control the behavior for each repository, keyed
+  Mapping of special settings to control the behavior for each repository,
-  by the repository name.
+  keyed by the repository name.
 
 ``flags``
   A list of flags attached to the repository.
@@ -446,6 +449,11 @@ The top level of a deliverable file is a mapping with keys:
     Stable branch names track upstream release names, rather than
     OpenStack series names.
 
+``cycle-highlights``
+  RST formatted notes of some of the top new features or changes you would like
+  to point out for this release cycle. These highlights are compiled per team
+  and published to ``releases.openstack.org/$SERIES/highlights.html``.
+
 ``branches``
   A list of the branches for the deliverable.
 

doc/source/queens/highlights.rst

@@ -0,0 +1,7 @@
+=========================
+Queens Release Highlights
+=========================
+
+.. serieshighlights::
+   :series: queens
+

doc/source/queens/index.rst

@@ -9,6 +9,11 @@ Projected Release Date: 28 February 2018
 
    schedule
 
+.. toctree::
+   :hidden:
+
+   highlights
 
 .. deliverable::
    :series: queens
+

openstack_releases/schema.yaml

@@ -39,6 +39,8 @@ properties:
   stable-branch-type:
     type: "string"
     enum: [ "std", "tagless", "upstream" ]
+  cycle-highlights:
+    type: "string"
   releases:
     type: "array"
     items:

openstack_releases/sphinxext.py

@@ -380,10 +380,65 @@ def _generate_team_pages(app):
     return
 
 
+class HighlightsDirective(rst.Directive):
+    """Directive to pull series highlights into docs output."""
+
+    option_spec = {
+        'series': directives.unchanged,
+    }
+
+    def _get_deliverable_highlights(self, series):
+        """Collects the highlights for the series.
+
+        :param series: The series to extract highlights from.
+        :returns: The available highlights for the series.
+        """
+        series_highlights = {}
+        series_deliverables = _deliverables.get_deliverables(None, series)
+        for deliv in series_deliverables:
+            series_info = deliv[3]
+            highlights = series_info.get('cycle-highlights')
+            if highlights:
+                # Add highlights to any existing notes already collected
+                notes = series_highlights.get(series_info['team'])
+                series_highlights[series_info['team']] = '{}{}\n\n'.format(
+                    notes, highlights)
+
+        return series_highlights
+
+    def run(self):
+        env = self.state.document.settings.env
+        app = env.app
+
+        # Get the series we are reporting on
+        series = self.options.get('series')
+        if not series:
+            raise self.error('series value must be set to a valid cycle name.')
+
+        result = ViewList()
+        series_highlights = self._get_deliverable_highlights(series)
+        source_name = '<{}>'.format(__name__)
+
+        for team in series_highlights.keys():
+            app.info('[highlights] rendering %s highlights for %s' %
+                     (team.title(), series))
+
+            result.append(team.title(), source_name)
+            result.append('-' * len(team), source_name)
+            result.append(series_highlights[team], source_name)
+            result.append('', source_name)
+
+        node = nodes.section()
+        node.document = self.state.document
+        nested_parse_with_titles(self.state, result, node)
+        return node.children
+
+
 def setup(app):
     _initialize_deliverable_data(app)
     app.add_directive('deliverable', DeliverableDirective)
     app.add_directive('independent-deliverables',
                       IndependentDeliverablesDirective)
     app.add_directive('team', TeamDirective)
+    app.add_directive('serieshighlights', HighlightsDirective)
     _generate_team_pages(app)