def _create_perfdocs(self):
'''
Creates the perfdocs documentation.
:return: str path of the temp dir it is saved in
'''
# All directories that are kept in the perfdocs tree are valid,
# so use it to build up the documentation.
framework_docs = self.build_perfdocs_from_tree()
perfdocs_tmpdir = self._create_temp_dir()
# Save the documentation files
frameworks = []
for framework_name in sorted(framework_docs.keys()):
frameworks.append(framework_name)
save_file(framework_docs[framework_name],
os.path.join(perfdocs_tmpdir, framework_name))
# Get the main page and add the framework links to it
mainpage = read_file(os.path.join(self.templates_path, "index.rst"),
stringify=True)
fmt_frameworks = os.linesep.join(
[' :doc:`%s`' % name for name in frameworks])
fmt_mainpage = re.sub(r"{test_documentation}", fmt_frameworks,
mainpage)
save_file(fmt_mainpage, os.path.join(perfdocs_tmpdir, 'index'))
return perfdocs_tmpdir
def validate_rst_content(self, rst_path):
"""
Validate that the index file given has a {documentation} entry
so that the documentation can be inserted there.
:param str rst_path: Path to the RST file.
:return bool: True/False => Passed/Failed Validation
"""
rst_content = read_file(rst_path)
# Check for a {documentation} entry in some line,
# if we can't find one, then the validation fails.
valid = False
docs_match = re.compile(".*{documentation}.*")
for line in rst_content:
if docs_match.search(line):
valid = True
break
if not valid:
logger.warning(
"Cannot find a '{documentation}' entry in the given index file",
rst_path,
)
return valid
def build_perfdocs_from_tree(self):
'''
Builds up a document for each framework that was found.
:return dict: A dictionary containing a mapping from each framework
to the document that was built for it, i.e:
{
framework_name: framework_document,
...
}
'''
def _append_rst_section(title, content, documentation, type=None):
'''
Adds a section to the documentation with the title as the type mentioned
and paragraph as content mentioned.
:param title: title of the section
:param content: content of section paragraph
:param documentation: documentation object to add section to
:param type: type of the title heading
'''
heading_map = {'H4': '-', 'H5': '^'}
heading_symbol = heading_map.get(type, '-')
documentation.extend(
[title, heading_symbol * len(title), content, ''])
# Using the verified `perfdocs_tree`, build up the documentation.
frameworks_info = {}
for framework in self._perfdocs_tree:
yaml_content = read_yaml(
os.path.join(framework['path'], framework['yml']))
rst_content = read_file(os.path.join(framework['path'],
framework['rst']),
stringify=True)
# Gather all tests and descriptions and format them into
# documentation content
documentation = []
suites = yaml_content['suites']
for suite_name in sorted(suites.keys()):
suite_info = suites[suite_name]
# Add the suite with an H4 heading
_append_rst_section(suite_name.capitalize(),
suite_info['description'],
documentation,
type="H4")
tests = suite_info.get('tests', {})
for test_name in sorted(tests.keys()):
documentation.extend(
self._verifier._gatherer.framework_gatherers[
yaml_content["name"]].build_test_description(
test_name, tests[test_name]))
# Insert documentation into `.rst` file
framework_rst = re.sub(r'{documentation}',
os.linesep.join(documentation), rst_content)
frameworks_info[yaml_content['name']] = framework_rst
return frameworks_info
def _create_perfdocs(self):
"""
Creates the perfdocs documentation.
:return: str path of the temp dir it is saved in
"""
# All directories that are kept in the perfdocs tree are valid,
# so use it to build up the documentation.
framework_docs = self.build_perfdocs_from_tree()
perfdocs_tmpdir = self._create_temp_dir()
# Save the documentation files
frameworks = []
for framework_name in sorted(framework_docs.keys()):
frameworks.append(framework_name)
save_file(
framework_docs[framework_name]["dynamic"],
os.path.join(perfdocs_tmpdir, framework_name),
)
for static_name in framework_docs[framework_name]["static"]:
save_file(
static_name["content"],
os.path.join(perfdocs_tmpdir, static_name["file"].split(".")[0]),
)
# Get the main page and add the framework links to it
mainpage = read_file(
os.path.join(self.templates_path, "index.rst"), stringify=True
)
fmt_frameworks = os.linesep.join(
[" * :doc:`%s`" % name for name in frameworks]
)
fmt_mainpage = re.sub(r"{test_documentation}", fmt_frameworks, mainpage)
save_file(fmt_mainpage, os.path.join(perfdocs_tmpdir, "index"))
return perfdocs_tmpdir
def build_perfdocs_from_tree(self):
"""
Builds up a document for each framework that was found.
:return dict: A dictionary containing a mapping from each framework
to the document that was built for it, i.e:
{
framework_name: framework_document,
...
}
"""
def _append_rst_section(title, content, documentation, type=None):
"""
Adds a section to the documentation with the title as the type mentioned
and paragraph as content mentioned.
:param title: title of the section
:param content: content of section paragraph
:param documentation: documentation object to add section to
:param type: type of the title heading
"""
heading_map = {"H4": "-", "H5": "^"}
heading_symbol = heading_map.get(type, "-")
documentation.extend([title, heading_symbol * len(title), content, ""])
# Using the verified `perfdocs_tree`, build up the documentation.
frameworks_info = {}
for framework in self._perfdocs_tree:
yaml_content = read_yaml(os.path.join(framework["path"], framework["yml"]))
rst_content = read_file(
os.path.join(framework["path"], framework["rst"]), stringify=True
)
# Gather all tests and descriptions and format them into
# documentation content
documentation = []
suites = yaml_content["suites"]
for suite_name in sorted(suites.keys()):
suite_info = suites[suite_name]
# Add the suite with an H4 heading
_append_rst_section(
suite_name.capitalize(),
suite_info["description"],
documentation,
type="H4",
)
tests = suite_info.get("tests", {})
for test_name in sorted(tests.keys()):
documentation.extend(
self._verifier._gatherer.framework_gatherers[
yaml_content["name"]
].build_test_description(
test_name, tests[test_name], suite_name
)
)
documentation.append("")
# Insert documentation into `.rst` file
framework_rst = re.sub(
r"{documentation}", os.linesep.join(documentation), rst_content
)
frameworks_info[yaml_content["name"]] = {
"dynamic": framework_rst,
"static": [],
}
# For static `.rst` file
for static_file in framework["static"]:
frameworks_info[yaml_content["name"]]["static"].append(
{
"file": static_file,
"content": read_file(
os.path.join(framework["path"], static_file), stringify=True
),
}
)
return frameworks_info
def build_perfdocs_from_tree(self):
"""
Builds up a document for each framework that was found.
:return dict: A dictionary containing a mapping from each framework
to the document that was built for it, i.e:
{
framework_name: framework_document,
...
}
"""
# Using the verified `perfdocs_tree`, build up the documentation.
frameworks_info = {}
for framework in self._perfdocs_tree:
yaml_content = read_yaml(
os.path.join(framework["path"], framework["yml"]))
rst_content = read_file(os.path.join(framework["path"],
framework["rst"]),
stringify=True)
# Gather all tests and descriptions and format them into
# documentation content
documentation = []
suites = yaml_content["suites"]
for suite_name in sorted(suites.keys()):
suite_info = suites[suite_name]
# Add the suite section
documentation.extend(
self._verifier._gatherer.framework_gatherers[
yaml_content["name"]].build_suite_section(
suite_name, suite_info["description"]))
tests = suite_info.get("tests", {})
for test_name in sorted(tests.keys()):
gatherer = self._verifier._gatherer.framework_gatherers[
yaml_content["name"]]
test_description = gatherer.build_test_description(
test_name, tests[test_name], suite_name)
documentation.extend(test_description)
documentation.append("")
# Insert documentation into `.rst` file
framework_rst = re.sub(r"{documentation}",
"\n".join(documentation), rst_content)
frameworks_info[yaml_content["name"]] = {
"dynamic": framework_rst,
"static": [],
}
# For static `.rst` file
for static_file in framework["static"]:
frameworks_info[yaml_content["name"]]["static"].append({
"file":
static_file,
"content":
read_file(os.path.join(framework["path"], static_file),
stringify=True),
})
return frameworks_info