deb-designate/doc/ext/support_matrix.py
Graham Hayes 374463d8e8 Add Backend grading, and associated docs page
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
2015-05-28 17:03:56 +01:00

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')