def execution_sub_steps_description(self) -> docs.ParagraphItem:
return lists.HeaderContentList([
docs.list_item(self._tp.text('execution of {phase[setup]:syntax}')),
docs.list_item(docs.text(post_setup_validation_step_name(self._setup))),
docs.list_item(docs.text('execution of remaining phases')),
],
lists.Format(lists.ListType.ORDERED_LIST,
custom_separations=docs.SEPARATION_OF_HEADER_AND_CONTENTS)
)
def _act_examples(tp: TextParser) -> sections.SectionConstructor:
return sections.section(
docs.text('Examples'),
sections.constant_contents(
docs.section_contents(tp.fnap(_ACT_EXAMPLES))
)
)
def _act_examples(tp: TextParser) -> sections.SectionConstructor:
return sections.section(
docs.text('Examples'),
sections.constant_contents(
docs.section_contents(tp.fnap(_ACT_EXAMPLES))
)
)
def with_or_without_name(do_include_name: bool,
name: str,
contents_renderer: ArticleContentsConstructor) -> SectionContentsConstructor:
if do_include_name:
return _WithElementNameConstructor(text(name), contents_renderer)
else:
return sections.contents_from_article_contents(contents_renderer)
def with_or_without_name(
do_include_name: bool, name: str,
contents_renderer: ArticleContentsConstructor
) -> SectionContentsConstructor:
if do_include_name:
return _WithElementNameConstructor(text(name), contents_renderer)
else:
return sections.contents_from_article_contents(contents_renderer)
def test(self):
cases = [
Case(
'test_singleton_element_without_contents',
items=
[HeaderContentListItem(text('header'))],
expected=
'<root>'
'<dl>'
'<dt>header</dt>'
'</dl>'
'</root>'
),
Case(
'test_singleton_element_with_multiple_content_paragraphs',
items=
[HeaderContentListItem(text('header'),
[para('ignored'),
para('ignored')])],
expected=
'<root>'
'<dl>'
'<dt>header</dt>'
'<dd>'
'<p>every para text</p>'
'<p>every para text</p>'
'</dd>'
'</dl>'
'</root>'
),
]
for case in cases:
with self.subTest(case.name):
root = Element('root')
the_list = HeaderContentList(case.items, Format(ListType.VARIABLE_LIST))
# ACT #
ret_val = sut.render(TextRenderer(TARGET_RENDERER),
ConstantPRenderer('every para text'),
root, the_list)
# ASSERT #
xml_string = as_unicode_str(root)
self.assertEqual(case.expected,
xml_string)
self.assertIs(list(root)[0],
ret_val)
def test_conf_param_with_only_single_line_description(self):
# ARRANGE #
doc = ConfigurationParameterTestImpl(
'conf_param_name', Description(text('single line name'), []),
'default value')
constructor = sut.IndividualConfParamConstructor(doc)
# ACT #
actual = constructor.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def test_concept_with_complex_description(self):
# ARRANGE #
concept = PlainConceptTestImpl(a_name(Name('name', 'names')),
Description(text('single line name'),
[para('rest paragraph')]))
renderer = sut.IndividualConceptConstructor(concept)
# ACT #
actual = renderer.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def apply(self, environment: ConstructionEnvironment) -> doc.SectionContents:
sections = []
for test_case_phase_help in self.test_case_help.phase_helps_in_order_of_execution:
if test_case_phase_help.has_instructions:
renderer = instruction_set_constructor(
test_case_phase_help.instruction_set,
instruction_group_by=test_case_phase_help.instruction_group_by)
sections.append(docs.Section(text(test_case_phase_help.name.syntax),
renderer.apply(environment)))
return doc.SectionContents([], sections)
def test_concept_with_complex_description(self):
# ARRANGE #
concept = PlainConceptTestImpl(
a_name(Name('name', 'names')),
Description(text('single line name'), [para('rest paragraph')]))
renderer = sut.IndividualConceptConstructor(concept)
# ACT #
actual = renderer.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def test_conf_param_with_complex_description(self):
# ARRANGE #
concept = ConfigurationParameterTestImpl(
'conf_param_name',
Description(text('single line name'), [para('rest paragraph')]),
'default value')
constructor = sut.IndividualConfParamConstructor(concept)
# ACT #
actual = constructor.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def test_conf_param_with_complex_description(self):
# ARRANGE #
concept = ConfigurationParameterTestImpl('conf_param_name',
Description(text('single line name'),
[para('rest paragraph')]),
'default value')
constructor = sut.IndividualConfParamConstructor(concept)
# ACT #
actual = constructor.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def test_conf_param_with_only_single_line_description(self):
# ARRANGE #
doc = ConfigurationParameterTestImpl('conf_param_name',
Description(text('single line name'),
[]),
'default value')
constructor = sut.IndividualConfParamConstructor(doc)
# ACT #
actual = constructor.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def section(self,
header_or_text,
paragraphs_text: str,
extra: Optional[Mapping[str, Any]] = None) -> docs.Section:
"""
:param header_or_text: If a `str` it is formatted using `self.format`.
:param paragraphs_text: Parsed using `self.fnap`.
"""
header = header_or_text
if not isinstance(header_or_text, docs.Text):
header = docs.text(self.format(header_or_text, extra))
return docs.section(header, self.fnap(paragraphs_text, extra))
def apply(self, environment: ConstructionEnvironment) -> doc.SectionContents:
sections = []
for phase_and_instruction_description in self.phase_and_instruction_description_list:
man_page_renderer = render_instruction.instruction_doc_section_contents_constructor(
phase_and_instruction_description[1])
phase_section = doc.Section(text(phase_and_instruction_description[0].syntax),
man_page_renderer.apply(environment))
sections.append(phase_section)
initial_paragraphs = []
if len(self.phase_and_instruction_description_list) > 1:
initial_paragraphs = [para('The instruction "%s" exists in multiple phases.' % self.instruction_name)]
return doc.SectionContents(initial_paragraphs, sections)
def apply(self,
environment: ConstructionEnvironment) -> doc.SectionContents:
sections = []
for test_case_phase_help in self.test_case_help.phase_helps_in_order_of_execution:
if test_case_phase_help.has_instructions:
renderer = instruction_set_constructor(
test_case_phase_help.instruction_set,
instruction_group_by=test_case_phase_help.
instruction_group_by)
sections.append(
docs.Section(text(test_case_phase_help.name.syntax),
renderer.apply(environment)))
return doc.SectionContents([], sections)
def test(self):
cases = [
Case('test_singleton_element_without_contents',
items=[HeaderContentListItem(text('header'))],
expected='<root>'
'<dl>'
'<dt>header</dt>'
'</dl>'
'</root>'),
Case('test_singleton_element_with_multiple_content_paragraphs',
items=[
HeaderContentListItem(
text('header'),
[para('ignored'), para('ignored')])
],
expected='<root>'
'<dl>'
'<dt>header</dt>'
'<dd>'
'<p>every para text</p>'
'<p>every para text</p>'
'</dd>'
'</dl>'
'</root>'),
]
for case in cases:
with self.subTest(case.name):
root = Element('root')
the_list = HeaderContentList(case.items,
Format(ListType.VARIABLE_LIST))
# ACT #
ret_val = sut.render(TextRenderer(TARGET_RENDERER),
ConstantPRenderer('every para text'),
root, the_list)
# ASSERT #
xml_string = as_unicode_str(root)
self.assertEqual(case.expected, xml_string)
self.assertIs(list(root)[0], ret_val)
def apply(self,
environment: ConstructionEnvironment) -> doc.SectionContents:
sections = []
for phase_and_instruction_description in self.phase_and_instruction_description_list:
man_page_renderer = render_instruction.instruction_doc_section_contents_constructor(
phase_and_instruction_description[1])
phase_section = doc.Section(
text(phase_and_instruction_description[0].syntax),
man_page_renderer.apply(environment))
sections.append(phase_section)
initial_paragraphs = []
if len(self.phase_and_instruction_description_list) > 1:
initial_paragraphs = [
para('The instruction "%s" exists in multiple phases.' %
self.instruction_name)
]
return doc.SectionContents(initial_paragraphs, sections)
def evaluation_description(self) -> List[ParagraphItem]:
op_eval_lay_l_to_r = [
operator.name for operator in self.infix_operators__list
if operator.value.description().
operand_evaluation__lazy__left_to_right
]
if not op_eval_lay_l_to_r:
return []
operators_header = ', '.join(op_eval_lay_l_to_r)
list_item = docs.simple_list(
[
lists.HeaderContentListItem(
docs.text(operators_header),
self._tp.fnap(_OPERANDS__LAZY__LEFT_TO_RIGHT))
],
lists.ListType.VARIABLE_LIST,
)
return [list_item]
def _entities_help() -> List[cli_syntax.Synopsis]:
def row(names: EntityTypeNames) -> List[docs.TableCell]:
return [
docs.text_cell(doc_format.syntax_text(names.identifier)),
docs.text_cell(names.name.plural.capitalize()),
]
entities_table = docs.plain_table(
map(row, ALL_ENTITY_TYPES_IN_DISPLAY_ORDER))
arguments = [
arg.Single(arg.Multiplicity.MANDATORY, _c(clo.HELP)),
arg.Single(arg.Multiplicity.MANDATORY, _n('ENTITY-TYPE')),
arg.Single(arg.Multiplicity.OPTIONAL, _n('ENTITY-NAME'))
]
single_line_description = 'Lists all entities of a type; or describes a given entity.'
return [
cli_syntax.Synopsis(arg.CommandLine(arguments),
docs.text(single_line_description),
[entities_table])
]
def _entities_help() -> List[cli_syntax.Synopsis]:
def row(names: EntityTypeNames) -> List[docs.TableCell]:
return [
docs.text_cell(doc_format.syntax_text(names.identifier)),
docs.text_cell(names.name.plural.capitalize()),
]
entities_table = docs.plain_table(map(row, ALL_ENTITY_TYPES_IN_DISPLAY_ORDER))
arguments = [
arg.Single(arg.Multiplicity.MANDATORY,
_c(clo.HELP)),
arg.Single(arg.Multiplicity.MANDATORY,
_n('ENTITY-TYPE')),
arg.Single(arg.Multiplicity.OPTIONAL,
_n('ENTITY-NAME'))
]
single_line_description = 'Lists all entities of a type; or describes a given entity.'
return [
cli_syntax.Synopsis(arg.CommandLine(arguments),
docs.text(single_line_description),
[entities_table])
]
class SectionDocumentationConstructorBase(ArticleContentsConstructor):
CONTENTS_HEADER = docs.text('Contents')
def __init__(self, section_documentation: SectionDocumentation,
section_concept_name: str,
instructions_section_header: docs.Text):
self.__section_documentation = section_documentation
self.__section_concept_name = section_concept_name
self.__instructions_section_header = instructions_section_header
def _default_section_info(
self, default_section_name: str) -> List[docs.ParagraphItem]:
ret_val = []
if self.__section_documentation.name.plain == default_section_name:
ret_val.append(default_section_para(self.__section_concept_name))
return ret_val
def _instruction_cross_ref_text(self, instr_name: str) -> docs.Text:
return docs.cross_reference(
instruction_name_text(instr_name),
self.__section_documentation.section_info.
instruction_cross_reference_target(instr_name),
allow_rendering_of_visible_extra_target_text=False)
def _add_section_for_instructions(self,
environment: ConstructionEnvironment,
output: List[docs.SectionItem]):
if self.__section_documentation.has_instructions:
renderer = instruction_set_constructor(
self.__section_documentation.instruction_set,
self._instruction_cross_ref_text,
instruction_group_by=self.__section_documentation.
instruction_group_by)
output.append(
docs.Section(self.__instructions_section_header,
renderer.apply(environment)))
def _files_sections(
files: Optional[docs.SectionContents]) -> List[docs.Section]:
if not files:
return []
return [docs.Section(docs.text('FILES'), files)]
def description(self) -> DescriptionWithSubSections:
return DescriptionWithSubSections(docs.text(_SINGLE_LINE_DESCRIPTION),
docs.SectionContents([], []))
def _outcome_sections(
outcome: Optional[docs.SectionContents]) -> List[docs.Section]:
if not outcome:
return []
return [docs.Section(docs.text('OUTCOME'), outcome)]
def name_and_single_line_description(self) -> Text:
return docs.text(self.name_and_single_line_description_str())
def _synopsis(additional_arguments: list,
single_line_description: str) -> cli_syntax.Synopsis:
arguments = [_c(clo.HELP)] + additional_arguments
return cli_syntax.Synopsis(arg.CommandLine(list(map(_single_mandatory_arg, arguments))),
docs.text(single_line_description))
def name_parts_description() -> Section:
return Section(docs.text('File name parts'),
docs.SectionContents([_name_parts_table()]))
def description(self) -> DescriptionWithSubSections:
text = '{}s help system.'.format(formatting.program_name(program_info.PROGRAM_NAME))
return DescriptionWithSubSections(docs.text(text),
empty_section_contents())
def description_section(contents: doc.SectionContents) -> doc.Section:
return doc.Section(docs.text('DESCRIPTION'), contents)
def _synopsis(additional_arguments: list,
single_line_description: str) -> cli_syntax.Synopsis:
arguments = [_c(clo.HELP)] + additional_arguments
return cli_syntax.Synopsis(
arg.CommandLine(list(map(_single_mandatory_arg, arguments))),
docs.text(single_line_description))
def test_non_empty(self):
# ARRANGE #
cases = [
Case('test_singleton_element_without_contents',
items=
[HeaderContentListItem(text('header'))],
expected=
'<root>'
'<{L}><li>header</li></{L}>'
'</root>',
),
Case('test_multiple_element_without_contents',
items=
[HeaderContentListItem(text('header 1')),
HeaderContentListItem(text('header 2'))],
expected=
'<root>'
'<{L}>'
'<li>header 1</li>'
'<li>header 2</li>'
'</{L}>'
'</root>',
),
Case('test_single_element_with_single_para_contents',
items=
[HeaderContentListItem(text('header'),
paras('ignored'))],
expected=
'<root>'
'<{L}>'
'<li>header<p>every para text</p></li>'
'</{L}>'
'</root>',
),
Case('test_single_element_with_multiple_para_contents',
items=
[HeaderContentListItem(text('header'),
[para('ignored'),
para('ignored')])],
expected=
'<root>'
'<{L}>'
'<li>header'
'<p>every para text</p>'
'<p>every para text</p>'
'</li>'
'</{L}>'
'</root>',
),
]
for list_type, element in [(ListType.ITEMIZED_LIST, 'ul'),
(ListType.ORDERED_LIST, 'ol')]:
for case in cases:
with self.subTest(list_type=list_type, case=case.name):
root = Element('root')
the_list = HeaderContentList(case.items, Format(list_type))
# ACT #
ret_val = sut.render(TextRenderer(TARGET_RENDERER),
ConstantPRenderer('every para text'),
root, the_list)
# ASSERT #
expected = case.expected.format(L=element)
xml_string = as_unicode_str(root)
self.assertEqual(expected,
xml_string)
self.assertIs(list(root)[0],
ret_val)
def synopsis_section(contents: doc.SectionContents) -> doc.Section:
return doc.Section(docs.text('SYNOPSIS'), contents)
def description(self) -> DescriptionWithSubSections:
text = '{}s help system.'.format(
formatting.program_name(program_info.PROGRAM_NAME))
return DescriptionWithSubSections(docs.text(text),
empty_section_contents())
def instructions_section_header(self) -> docs.Text:
return docs.text('Additional instructions')
def _synopsis_for_args(argument_usages: Sequence[arg.ArgumentUsage],
single_line_description: str) -> cli_syntax.Synopsis:
return cli_syntax.Synopsis(arg.CommandLine(argument_usages,
prefix=program_info.PROGRAM_NAME),
docs.text(single_line_description))
def single_line_description(self) -> Text:
return docs.text(self.single_line_description_str())
def _synopsis_for_args(argument_usages: Sequence[arg.ArgumentUsage],
single_line_description: str) -> cli_syntax.Synopsis:
return cli_syntax.Synopsis(arg.CommandLine(argument_usages,
prefix=program_info.PROGRAM_NAME),
docs.text(single_line_description))
def name_and_single_line_description(self) -> Text:
return docs.text(self.name_and_single_line_description_str())
def purpose(self) -> Description:
return Description(
docs.text('Single line purpose for phase ' + self.name.syntax),
[docs.para('Rest of purpose for phase ' + self.name.syntax)])
def instructions_section_header(self) -> docs.Text:
return docs.text('Additional instructions')
from exactly_lib.util.textformat.structure import structures as docs
INSTRUCTIONS_SECTION_HEADER = docs.text('Instructions')
def section_constructor(
partition: EntitiesPartition) -> SectionConstructor:
return sections.section(
docs.text(partition.partition_names_setup.header),
EntitiesListConstructor(self.entity_2_summary_paragraphs,
partition.entity_doc_list))
def test_non_empty(self):
# ARRANGE #
cases = [
Case(
'test_singleton_element_without_contents',
items=[HeaderContentListItem(text('header'))],
expected='<root>'
'<{L}><li>header</li></{L}>'
'</root>',
),
Case(
'test_multiple_element_without_contents',
items=[
HeaderContentListItem(text('header 1')),
HeaderContentListItem(text('header 2'))
],
expected='<root>'
'<{L}>'
'<li>header 1</li>'
'<li>header 2</li>'
'</{L}>'
'</root>',
),
Case(
'test_single_element_with_single_para_contents',
items=[
HeaderContentListItem(text('header'), paras('ignored'))
],
expected='<root>'
'<{L}>'
'<li>header<p>every para text</p></li>'
'</{L}>'
'</root>',
),
Case(
'test_single_element_with_multiple_para_contents',
items=[
HeaderContentListItem(
text('header'),
[para('ignored'), para('ignored')])
],
expected='<root>'
'<{L}>'
'<li>header'
'<p>every para text</p>'
'<p>every para text</p>'
'</li>'
'</{L}>'
'</root>',
),
]
for list_type, element in [(ListType.ITEMIZED_LIST, 'ul'),
(ListType.ORDERED_LIST, 'ol')]:
for case in cases:
with self.subTest(list_type=list_type, case=case.name):
root = Element('root')
the_list = HeaderContentList(case.items, Format(list_type))
# ACT #
ret_val = sut.render(TextRenderer(TARGET_RENDERER),
ConstantPRenderer('every para text'),
root, the_list)
# ASSERT #
expected = case.expected.format(L=element)
xml_string = as_unicode_str(root)
self.assertEqual(expected, xml_string)
self.assertIs(list(root)[0], ret_val)
def single_line_description(self) -> Text:
return docs.text(self.single_line_description_str())
def _outcome_sections(outcome: Optional[docs.SectionContents]) -> List[docs.Section]:
if not outcome:
return []
return [docs.Section(docs.text('OUTCOME'), outcome)]
def description(self) -> DescriptionWithSubSections:
return DescriptionWithSubSections(docs.text(_SINGLE_LINE_DESCRIPTION),
docs.SectionContents([], []))
def _files_sections(files: Optional[docs.SectionContents]) -> List[docs.Section]:
if not files:
return []
return [docs.Section(docs.text('FILES'), files)]
def purpose(self) -> Description:
return Description(
docs.text(
'Lists test suites (sub suites) that are part of the suite.'),
[])
def purpose(self) -> Description:
return Description(text('Single line purpose for phase ' + self.name.syntax),
[para('Rest of purpose for phase ' + self.name.syntax)])
def purpose(self) -> Description:
return Description(docs.text('Lists the test cases that are part of the suite.'),
[])
def description_section_if_non_empty(contents: doc.SectionContents) -> list:
if contents.is_empty:
return []
else:
return [doc.Section(docs.text('DESCRIPTION'), contents)]
from exactly_lib.definitions import doc_format
from exactly_lib.util.textformat.structure import structures as docs
DESCRIPTION__HEADER__UPPERCASE = docs.text('DESCRIPTION')
DESCRIPTION__HEADER__CAPITALIZED = docs.text('Description')
NOTES__HEADER__UPPERCASE = docs.text('NOTES')
NOTES__HEADER__CAPITALIZED = docs.text('Notes')
NOTE_LINE_HEADER = 'Note:'
OUTCOME__HEADER__UPPERCASE = docs.text('OUTCOME')
SYNOPSIS_TEXT = docs.text('SYNOPSIS')
WHERE_PARA = docs.para(doc_format.text_as_header('where'))
FORMS_PARA = docs.para(doc_format.text_as_header('Forms:'))
def section_constructor(partition: EntitiesPartition) -> SectionConstructor:
return sections.section(
docs.text(partition.partition_names_setup.header),
EntitiesListConstructor(self.entity_2_summary_paragraphs,
partition.entity_doc_list))
