From a4210c19629751bc20ff75cc5b8c00b315107101 Mon Sep 17 00:00:00 2001 From: Tom Fifield Date: Wed, 28 Dec 2016 14:03:17 +0800 Subject: [PATCH] Add structure for providing team/wg tables This commit adds two files to the reference documents: * teams.yaml - to be used as a list of UC-approved teams * working-groups.yaml - to be used as a list of UC-approved WGs The sphinx setup and index page is changed to allow the display of the list of teams and list of working groups. Change-Id: Ieaba6979eb1969c213565bfbbf45fdbe3257c2d2 --- doc/source/_exts/members.py | 11 ++- doc/source/_exts/teamtable.py | 133 ++++++++++++++++++++++++++++++++++ doc/source/conf.py | 1 + doc/source/index.rst | 14 ++++ reference/teams.yaml | 6 ++ reference/working-groups.yaml | 7 ++ test-requirements.txt | 1 + 7 files changed, 169 insertions(+), 4 deletions(-) create mode 100644 doc/source/_exts/teamtable.py create mode 100644 reference/teams.yaml create mode 100644 reference/working-groups.yaml diff --git a/doc/source/_exts/members.py b/doc/source/_exts/members.py index c4965ed..053718b 100644 --- a/doc/source/_exts/members.py +++ b/doc/source/_exts/members.py @@ -75,11 +75,14 @@ class MembersTable(Table): # Handle the width settings and title try: + # Since docutils 0.13, get_column_widths returns a (widths, + # colwidths) tuple, where widths is a string (i.e. 'auto'). + # See https://sourceforge.net/p/docutils/patches/120/. col_widths = self.get_column_widths(len(self.HEADERS)) title, messages = self.make_title() - except SystemMessagePropagation, detail: + except SystemMessagePropagation as detail: return [detail.args[0]] - except Exception, err: + except Exception as err: error = self.state_machine.reporter.error( 'Error processing memberstable directive:\n%s' % err, nodes.literal_block(self.block_text, self.block_text), @@ -109,7 +112,7 @@ class MembersTable(Table): # Set up the column specifications # based on the widths. - tgroup = nodes.tgroup(cols=len(col_widths)) + tgroup = nodes.tgroup(cols=len(self.HEADERS)) table += tgroup tgroup.extend(nodes.colspec(colwidth=col_width) for col_width in col_widths) @@ -138,7 +141,7 @@ class MembersTable(Table): # in re match group with empty string. cell = row.get(self.HEADER_MAP[h]) or '' entry = nodes.entry() - para = nodes.paragraph(text=unicode(cell)) + para = nodes.paragraph(text=str(cell)) entry += para trow += entry rows.append(trow) diff --git a/doc/source/_exts/teamtable.py b/doc/source/_exts/teamtable.py new file mode 100644 index 0000000..9ade57d --- /dev/null +++ b/doc/source/_exts/teamtable.py @@ -0,0 +1,133 @@ +#!/usr/bin/env python + +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +"""Build a table of the current teams +""" + +from docutils import nodes +from docutils.parsers.rst.directives.tables import Table +from docutils.parsers.rst import directives + +import yaml + + +class TeamTable(Table): + """Insert the members table using the referenced file as source. + """ + HEADERS = ('Name', 'Chairs', 'Mission') + + option_spec = {'class': directives.class_option, + 'name': directives.unchanged, + 'datafile': directives.unchanged, + 'headers': directives.unchanged, + } + def run(self): + env = self.state.document.settings.env + app = env.app + + if self.options.get('headers') is not None: + self.HEADERS = self.options.get('headers').split(",") + # The required argument to the directive is the name of the + # file to parse. + datafile = self.options.get('datafile') + if not datafile: + error = self.state_machine.reporter.error( + 'No filename in teamtable directive', + nodes.literal_block(self.block_text, self.block_text), + line=self.lineno) + return [error] + + # Handle the width settings and title + try: + # Since docutils 0.13, get_column_widths returns a (widths, + # colwidths) tuple, where widths is a string (i.e. 'auto'). + # See https://sourceforge.net/p/docutils/patches/120/. + col_widths = self.get_column_widths(len(self.HEADERS)) + title, messages = self.make_title() + except SystemMessagePropagation as detail: + return [detail.args[0]] + except Exception as err: + error = self.state_machine.reporter.error( + 'Error processing memberstable directive:\n%s' % err, + nodes.literal_block(self.block_text, self.block_text), + line=self.lineno, + ) + return [error] + + # Now find the real path to the file, relative to where we are. + rel_filename, filename = env.relfn2path(datafile) + + app.info('loading teamtable') + app.info('reading %s' % filename) + with open(filename, 'r') as f: + _teams_yaml = yaml.load(f.read()) + + table = nodes.table() + + # Set up the column specifications + # based on the widths. + tgroup = nodes.tgroup(cols=len(self.HEADERS)) + table += tgroup + tgroup.extend(nodes.colspec(colwidth=col_width) + for col_width in col_widths) + + # Set the headers + thead = nodes.thead() + tgroup += thead + row_node = nodes.row() + thead += row_node + row_node.extend( + nodes.entry(h, nodes.paragraph(text=h)) + for h in self.HEADERS + ) + + # The body of the table is made up of rows. + # Each row contains a series of entries, + # and each entry contains a paragraph of text. + tbody = nodes.tbody() + tgroup += tbody + rows = [] + + all_teams = _teams_yaml + for team in sorted(all_teams.keys()): + trow = nodes.row() + # Iterate over the headers in the same order every time. + for h in self.HEADERS: + if h.lower() == "name": + cell = "

%s" % (all_teams[team]['url'], team) + entry = nodes.entry() + para = nodes.raw('', cell, format='html') + else: + # Get the cell value from the row data, replacing None + # in re match group with empty string. + cell = all_teams[team][h.lower()] or '' + entry = nodes.entry() + para = nodes.paragraph(text=str(cell)) + entry += para + trow += entry + rows.append(trow) + tbody.extend(rows) + + # Build the table node + table['classes'] += self.options.get('class', []) + self.add_name(table) + + if title: + table.insert(0, title) + + return [table] + messages + + +def setup(app): + app.add_directive('teamtable', TeamTable) diff --git a/doc/source/conf.py b/doc/source/conf.py index 85e396f..84acf4b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -33,6 +33,7 @@ extensions = [ 'sphinx.ext.extlinks', 'oslosphinx', 'members', + 'teamtable', ] todo_include_todos = True diff --git a/doc/source/index.rst b/doc/source/index.rst index 22d0b0b..2f39cb8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,20 @@ Current Members .. memberstable:: :datafile: ../../reference/members +Teams +=============== + +.. teamtable:: + :datafile: ../../reference/teams.yaml + +Working Groups +=============== + +.. teamtable:: + :datafile: ../../reference/working-groups.yaml + :headers: Name,Chairs,Status,Mission + + Reference documents and Resolutions =================================== diff --git a/reference/teams.yaml b/reference/teams.yaml new file mode 100644 index 0000000..5043aa5 --- /dev/null +++ b/reference/teams.yaml @@ -0,0 +1,6 @@ +Large Deployment Team: + chairs: Matt Van Winkle + mission: > + To discuss the needs and issues of those running large OpenStack deployments. + url: https://wiki.openstack.org/wiki/Large_Deployment_Team + diff --git a/reference/working-groups.yaml b/reference/working-groups.yaml new file mode 100644 index 0000000..680a01e --- /dev/null +++ b/reference/working-groups.yaml @@ -0,0 +1,7 @@ +AUC Recognition: + chairs: Shamail Tahir , Maish Saidel-Keesing + mission: > + To assist the User Committee with defining its constituency. + url: https://wiki.openstack.org/wiki/AUCRecognition + status: completed + diff --git a/test-requirements.txt b/test-requirements.txt index cfa7441..40bcba4 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -2,5 +2,6 @@ # of appearance. Changing the order has an impact on the overall integration # process, which may cause wedges in the gate later. # needed for doc build +docutils>=0.11,!=0.13.1 # OSI-Approved Open Source, Public Domain sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2 # BSD oslosphinx!=3.4.0,>=2.5.0 # Apache-2.0