374463d8e8
This adds a parameter to the backend class the defines its grade. It can be overridden in the support-matrix.ini file it needed. Change-Id: Icbcb3d88242c6d2de2c361722ddea85d4b585fca
395 lines
12 KiB
Python
395 lines
12 KiB
Python
# Copyright (C) 2014 Red Hat, Inc.
|
|
#
|
|
# 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.
|
|
|
|
"""
|
|
This provides a sphinx extension able to render the source/support-matrix.ini
|
|
file into the developer documentation.
|
|
|
|
It is used via a single directive in the .rst file
|
|
|
|
.. support_matrix::
|
|
|
|
"""
|
|
|
|
import ConfigParser
|
|
|
|
from docutils import nodes
|
|
from docutils.parsers import rst
|
|
from designate.backend.base import Backend
|
|
from designate.backend.agent_backend.base import AgentBackend
|
|
|
|
|
|
class SupportMatrix(object):
|
|
"""Represents the entire support matrix for Nova virt drivers
|
|
"""
|
|
|
|
def __init__(self):
|
|
# List of SupportMatrixFeature instances, describing
|
|
# all the features present in Nova virt drivers
|
|
self.grades = []
|
|
|
|
self.grade_names = {}
|
|
|
|
# Dict of (name, SupportMatrixTarget) enumerating
|
|
# all the hypervisor drivers that have data recorded
|
|
# for them in self.features. The 'name' dict key is
|
|
# the value from the SupportMatrixTarget.key attribute
|
|
self.backends = {}
|
|
|
|
|
|
class SupportMatrixGrade(object):
|
|
|
|
def __init__(self, key, title, notes, in_tree):
|
|
self.key = key
|
|
self.title = title
|
|
self.notes = notes
|
|
self.in_tree = in_tree
|
|
|
|
|
|
class SupportMatrixBackend(object):
|
|
|
|
def __init__(self, key, title, status,
|
|
maintainers=None, variations=None,
|
|
repository=None, type=None):
|
|
self.key = key
|
|
self.title = title
|
|
self.type = type
|
|
self.status = status
|
|
self.maintainers = maintainers
|
|
self.variations = variations
|
|
self.repository = repository
|
|
|
|
|
|
class SupportMatrixDirective(rst.Directive):
|
|
|
|
option_spec = {
|
|
'support-matrix': unicode,
|
|
}
|
|
|
|
def run(self):
|
|
matrix = self._load_support_matrix()
|
|
return self._build_markup(matrix)
|
|
|
|
def _load_support_matrix(self):
|
|
"""Reads the support-matrix.ini file and populates an instance
|
|
of the SupportMatrix class with all the data.
|
|
|
|
:returns: SupportMatrix instance
|
|
"""
|
|
|
|
cfg = ConfigParser.SafeConfigParser()
|
|
env = self.state.document.settings.env
|
|
fname = self.options.get("support-matrix",
|
|
"support-matrix.ini")
|
|
rel_fpath, fpath = env.relfn2path(fname)
|
|
with open(fpath) as fp:
|
|
cfg.readfp(fp)
|
|
|
|
# This ensures that the docs are rebuilt whenever the
|
|
# .ini file changes
|
|
env.note_dependency(rel_fpath)
|
|
|
|
matrix = SupportMatrix()
|
|
|
|
# The 'targets' section is special - it lists all the
|
|
# hypervisors that this file records data for
|
|
for item in cfg.options("backends"):
|
|
if not item.startswith("backend-impl-"):
|
|
continue
|
|
|
|
# The driver string will optionally contain
|
|
# a hypervisor and architecture qualifier
|
|
# so we expect between 1 and 3 components
|
|
# in the name
|
|
key = item[13:]
|
|
title = cfg.get("backends", item)
|
|
name = key.split("-")
|
|
|
|
try:
|
|
status = cfg.get("backends.%s" % item, "status")
|
|
except ConfigParser.NoOptionError:
|
|
if cfg.get("backends.%s" % item, "type") == "xfr":
|
|
backend = Backend.get_driver(name[0])
|
|
elif cfg.get("backends.%s" % item, "type") == "agent":
|
|
backend = AgentBackend.get_driver(name[0])
|
|
status = backend.__backend_status__
|
|
|
|
if len(name) == 1:
|
|
backend = SupportMatrixBackend(
|
|
key, title, status, name[0])
|
|
elif len(name) == 2:
|
|
backend = SupportMatrixBackend(
|
|
key, title, status, name[0], variations=name[1])
|
|
else:
|
|
raise Exception("'%s' field is malformed in '[%s]' section" %
|
|
(item, "DEFAULT"))
|
|
|
|
backend.in_tree = cfg.getboolean(
|
|
"backends.%s" % item, "in-tree")
|
|
backend.type = cfg.get(
|
|
"backends.%s" % item, "type")
|
|
backend.notes = cfg.get(
|
|
"backends.%s" % item, "notes")
|
|
backend.repository = cfg.get(
|
|
"backends.%s" % item, "repository")
|
|
backend.maintainers = cfg.get(
|
|
"backends.%s" % item, "maintainers")
|
|
|
|
matrix.backends[key] = backend
|
|
|
|
grades = cfg.get("grades", "valid-grades")
|
|
|
|
grades = grades.split(",")
|
|
|
|
for grade in grades:
|
|
title = cfg.get("grades.%s" % grade, "title")
|
|
notes = cfg.get("grades.%s" % grade, "notes")
|
|
in_tree = cfg.get("grades.%s" % grade, "in-tree")
|
|
|
|
matrix.grade_names[grade] = title
|
|
|
|
grade = SupportMatrixGrade(
|
|
grade, title, notes, in_tree)
|
|
|
|
matrix.grades.append(grade)
|
|
|
|
return matrix
|
|
|
|
def _build_markup(self, matrix):
|
|
"""Constructs the docutils content for the support matrix
|
|
"""
|
|
content = []
|
|
self._build_grade_listing(matrix, content)
|
|
self._build_grade_table(matrix, content)
|
|
self._build_backend_detail(matrix, content)
|
|
return content
|
|
|
|
def _build_backend_detail_table(self, backend, matrix):
|
|
|
|
table = nodes.table()
|
|
tgroup = nodes.tgroup(cols=2)
|
|
thead = nodes.thead()
|
|
tbody = nodes.tbody()
|
|
|
|
for i in range(2):
|
|
tgroup.append(nodes.colspec(colwidth=1))
|
|
|
|
tgroup.append(thead)
|
|
tgroup.append(tbody)
|
|
table.append(tgroup)
|
|
|
|
header = nodes.row()
|
|
blank = nodes.entry()
|
|
blank.append(nodes.emphasis(text=backend.title))
|
|
header.append(blank)
|
|
blank = nodes.entry()
|
|
header.append(blank)
|
|
thead.append(header)
|
|
|
|
graderow = nodes.row()
|
|
gradetitle = nodes.entry()
|
|
gradetitle.append(nodes.strong(text="Grade"))
|
|
gradetext = nodes.entry()
|
|
gradetext.append(nodes.paragraph(
|
|
text=matrix.grade_names[backend.status]))
|
|
graderow.append(gradetitle)
|
|
graderow.append(gradetext)
|
|
tbody.append(graderow)
|
|
|
|
treerow = nodes.row()
|
|
treetitle = nodes.entry()
|
|
treetitle.append(nodes.strong(text="In Tree"))
|
|
if bool(backend.in_tree):
|
|
status = u"\u2714"
|
|
else:
|
|
status = u"\u2716"
|
|
treetext = nodes.entry()
|
|
treetext.append(nodes.paragraph(text=status))
|
|
treerow.append(treetitle)
|
|
treerow.append(treetext)
|
|
tbody.append(treerow)
|
|
|
|
maintrow = nodes.row()
|
|
mainttitle = nodes.entry()
|
|
mainttitle.append(nodes.strong(text="Maintainers"))
|
|
mainttext = nodes.entry()
|
|
mainttext.append(nodes.paragraph(text=backend.maintainers))
|
|
maintrow.append(mainttitle)
|
|
maintrow.append(mainttext)
|
|
tbody.append(maintrow)
|
|
|
|
reporow = nodes.row()
|
|
repotitle = nodes.entry()
|
|
repotitle.append(nodes.strong(text="Repository"))
|
|
repotext = nodes.entry()
|
|
repotext.append(nodes.paragraph(text=backend.repository))
|
|
reporow.append(repotitle)
|
|
reporow.append(repotext)
|
|
tbody.append(reporow)
|
|
|
|
noterow = nodes.row()
|
|
notetitle = nodes.entry()
|
|
notetitle.append(nodes.strong(text="Notes"))
|
|
notetext = nodes.entry()
|
|
notetext.append(nodes.paragraph(text=backend.notes))
|
|
noterow.append(notetitle)
|
|
noterow.append(notetext)
|
|
tbody.append(noterow)
|
|
|
|
return table
|
|
|
|
def _build_backend_detail(self, matrix, content):
|
|
|
|
detailstitle = nodes.subtitle(text="Backend Details")
|
|
|
|
content.append(detailstitle)
|
|
|
|
for key in matrix.backends.keys():
|
|
|
|
content.append(
|
|
self._build_backend_detail_table(
|
|
matrix.backends[key],
|
|
matrix))
|
|
|
|
content.append(nodes.line())
|
|
|
|
return content
|
|
|
|
def _build_grade_listing(self, matrix, content):
|
|
|
|
summarytitle = nodes.title(text="Grades")
|
|
content.append(summarytitle)
|
|
table = nodes.table()
|
|
grades = matrix.grades
|
|
|
|
tablegroup = nodes.tgroup(cols=2)
|
|
summarybody = nodes.tbody()
|
|
summaryhead = nodes.thead()
|
|
|
|
for i in range(2):
|
|
tablegroup.append(nodes.colspec(colwidth=1))
|
|
tablegroup.append(summaryhead)
|
|
tablegroup.append(summarybody)
|
|
table.append(tablegroup)
|
|
content.append(table)
|
|
|
|
header = nodes.row()
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="Grade"))
|
|
header.append(blank)
|
|
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="Description"))
|
|
header.append(blank)
|
|
|
|
summaryhead.append(header)
|
|
|
|
for grade in grades:
|
|
item = nodes.row()
|
|
namecol = nodes.entry()
|
|
namecol.append(nodes.paragraph(text=grade.title))
|
|
item.append(namecol)
|
|
|
|
notescol = nodes.entry()
|
|
notescol.append(nodes.paragraph(text=grade.notes))
|
|
item.append(notescol)
|
|
|
|
summarybody.append(item)
|
|
|
|
return content
|
|
|
|
def _build_grade_table(self, matrix, content):
|
|
|
|
summarytitle = nodes.title(text="Backends - Summary")
|
|
summary = nodes.table()
|
|
cols = len(matrix.backends.keys())
|
|
cols += 2
|
|
summarygroup = nodes.tgroup(cols=cols)
|
|
summarybody = nodes.tbody()
|
|
summaryhead = nodes.thead()
|
|
|
|
for i in range(cols):
|
|
summarygroup.append(nodes.colspec(colwidth=1))
|
|
summarygroup.append(summaryhead)
|
|
summarygroup.append(summarybody)
|
|
summary.append(summarygroup)
|
|
content.append(summarytitle)
|
|
content.append(summary)
|
|
|
|
header = nodes.row()
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="Backend"))
|
|
header.append(blank)
|
|
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="Status"))
|
|
header.append(blank)
|
|
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="Type"))
|
|
header.append(blank)
|
|
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="In Tree"))
|
|
header.append(blank)
|
|
|
|
blank = nodes.entry()
|
|
blank.append(nodes.strong(text="Notes"))
|
|
header.append(blank)
|
|
summaryhead.append(header)
|
|
|
|
grades = matrix.grades
|
|
impls = matrix.backends.keys()
|
|
impls.sort()
|
|
for grade in grades:
|
|
for backend in impls:
|
|
if matrix.backends[backend].status == grade.key:
|
|
item = nodes.row()
|
|
namecol = nodes.entry()
|
|
namecol.append(
|
|
nodes.paragraph(text=matrix.backends[backend].title))
|
|
item.append(namecol)
|
|
|
|
statuscol = nodes.entry()
|
|
statuscol.append(nodes.paragraph(text=grade.title))
|
|
item.append(statuscol)
|
|
|
|
typecol = nodes.entry()
|
|
typecol.append(nodes.paragraph(
|
|
text=matrix.backends[backend].type))
|
|
item.append(typecol)
|
|
|
|
if bool(matrix.backends[backend].in_tree):
|
|
status = u"\u2714"
|
|
else:
|
|
status = u"\u2716"
|
|
|
|
intreecol = nodes.entry()
|
|
intreecol.append(nodes.paragraph(text=status))
|
|
item.append(intreecol)
|
|
|
|
notescol = nodes.entry()
|
|
notescol.append(nodes.paragraph(
|
|
text=matrix.backends[backend].notes))
|
|
item.append(notescol)
|
|
|
|
summarybody.append(item)
|
|
|
|
return content
|
|
|
|
|
|
def setup(app):
|
|
app.add_directive('support_matrix', SupportMatrixDirective)
|
|
app.add_stylesheet('support-matrix.css')
|