def row(name: str, file_name: str) -> List[TableCell]: return [ docs.cell(docs.paras(name)), docs.cell( docs.paras( file_name_text(sds.SUB_DIRECTORY__RESULT + '/' + file_name))) ]
def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( docs.paras('ced_at_start_of_phase'), [ 'FIRST_ENV_VAR', 'SECOND_ENV_VAR', ], tuple(docs.paras('prologue')), )
def test_with_syntax_elements_without_invokation_variants(self): description = InstructionDocumentationWithConstantValues( 'instruction name', 'single line description', 'main description rest', [InvokationVariant('invokation variant syntax', paras('invokation variant description rest'))], [SyntaxElementDescription('syntax element', paras('description rest'), [])]) actual = sut.instruction_doc_section_contents_constructor(description).apply(CONSTRUCTION_ENVIRONMENT) struct_check.is_section_contents.apply(self, actual)
def _dir_info_items_table(env_var_name: Text, rel_option: Text, env_var_description: str) -> ParagraphItem: return docs.first_column_is_header_table([ [ docs.cell(docs.paras(env_var_name)), docs.cell(docs.paras(env_var_description)), ], [ docs.cell(docs.paras(rel_option)), docs.cell(docs.paras('This option (accepted by many instructions) refers to this directory.')), ], ])
def _dir_info_items_table(symbol_name: Text, rel_option: Text, symbol_description: str) -> ParagraphItem: return docs.first_column_is_header_table([ [ docs.cell(docs.paras(symbol_name)), docs.cell(docs.paras(symbol_description)), ], [ docs.cell(docs.paras(rel_option)), docs.cell( docs.paras( 'The path relativity option that refers to this directory.' )), ], ])
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: purpose = self.doc.purpose() abstract_paras = docs.paras(purpose.single_line_description) return doc.ArticleContents( abstract_paras, self._section_contents(environment, purpose.rest))
def test_render(self): # ARRANGE # paragraphs = docs.paras('simple paragraph') document_variants = [ SuiteReporterDocTestImpl('as little content as possible'), SuiteReporterDocTestImpl('with main_description_rest', main_description_rest=paragraphs), SuiteReporterDocTestImpl('with syntax_of_output', syntax_of_output=paragraphs), SuiteReporterDocTestImpl('with exit_code_description', exit_code_description=paragraphs), SuiteReporterDocTestImpl( 'with syntax_of_output and exit_code_description', syntax_of_output=paragraphs, exit_code_description=paragraphs), SuiteReporterDocTestImpl('with everything', main_description_rest=paragraphs, syntax_of_output=paragraphs, exit_code_description=paragraphs), ] for doc in document_variants: with self.subTest(doc_name=doc.singular_name()): constructor = sut.IndividualSuiteReporterConstructor(doc) # ACT # actual = constructor.apply(CONSTRUCTION_ENVIRONMENT) # ASSERT # struct_check.is_article_contents.apply(self, actual)
def test_render(self): # ARRANGE # paragraphs = docs.paras('simple paragraph') document_variants = [ SuiteReporterDocTestImpl('as little content as possible'), SuiteReporterDocTestImpl('with main_description_rest', main_description_rest=paragraphs), SuiteReporterDocTestImpl('with syntax_of_output', syntax_of_output=paragraphs), SuiteReporterDocTestImpl('with exit_code_description', exit_code_description=paragraphs), SuiteReporterDocTestImpl('with syntax_of_output and exit_code_description', syntax_of_output=paragraphs, exit_code_description=paragraphs), SuiteReporterDocTestImpl('with everything', main_description_rest=paragraphs, syntax_of_output=paragraphs, exit_code_description=paragraphs), ] for doc in document_variants: with self.subTest(doc_name=doc.singular_name()): constructor = sut.IndividualSuiteReporterConstructor(doc) # ACT # actual = constructor.apply(CONSTRUCTION_ENVIRONMENT) # ASSERT # struct_check.is_article_contents.apply(self, actual)
def syntax_element_descriptions(self) -> list: return [ self._file_contents_sed(), rel_path_doc.path_element_2(self._src_rel_opt_arg_conf, docs.paras(the_path_of('an existing file.'))), self._transformation_sed(), ]
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: purpose = self.doc.purpose() abstract_paras = docs.paras(purpose.single_line_description) return doc.ArticleContents(abstract_paras, self._section_contents(environment, purpose.rest))
def test_hierarchy_with_sub_sections(self): # ARRANGE # target_factory = TargetInfoFactoryTestImpl(['target_component']) expected_section_contents_object1 = doc.empty_section_contents() expected_section_contents_object2 = docs.section_contents(docs.paras('testing testing')) expected_root_initial_para = docs.para('root initial paras') expected_root_initial_paras = [expected_root_initial_para] root_header = StringText('root header') sub_section_header_1 = 'sub1' sub_section_header_2 = 'sub2' sub_section_local_target_1 = 'sub-target1' sub_section_local_target_2 = 'sub-target2' object_to_test = sut.hierarchy( root_header, paragraphs.constant(expected_root_initial_paras), [sut.child(sub_section_local_target_1, sut.leaf(sub_section_header_1, section_contents(expected_section_contents_object1))), sut.child(sub_section_local_target_2, sut.leaf(sub_section_header_2, section_contents(expected_section_contents_object2))) ]) # EXPECTATION # expected_root_target_info = target_factory.root(root_header) sub1_target = target_factory.sub(sub_section_header_1, sub_section_local_target_1) sub2_target = target_factory.sub(sub_section_header_2, sub_section_local_target_2) target_info_node_assertion = equals_target_info_node( TargetInfoNode(expected_root_target_info, [ target_info_leaf(sub1_target), target_info_leaf(sub2_target), ]), mk_equals_cross_ref_id=equals_custom_cross_ref_test_impl) section_assertion2 = section_matches( target=equals_custom_cross_ref_test_impl(expected_root_target_info.target), header=asrt_para.equals_text(expected_root_target_info.presentation_text), contents=section_contents_matches( initial_paragraphs=asrt.matches_sequence([asrt.Is(expected_root_initial_para)]), sections=asrt.matches_sequence([ section_matches( target=equals_custom_cross_ref_test_impl(sub1_target.target), header=asrt_para.equals_text(sub1_target.presentation_text), contents=asrt.Is(expected_section_contents_object1)), section_matches( target=equals_custom_cross_ref_test_impl(sub2_target.target), header=asrt_para.equals_text(sub2_target.presentation_text), contents=asrt.Is(expected_section_contents_object2)), ]))) # ACT & ASSERT # self._act_and_assert(object_to_test, target_factory, target_info_node_assertion, section_assertion2)
def syntax_element_descriptions(self) -> List[SyntaxElementDescription]: ret_val = [ rel_path_doc.path_element(_DST_PATH_ARGUMENT.name, REL_OPT_ARG_CONF.options, docs.paras(the_path_of('a non-existing file.'))), ] ret_val += self._file_contents_doc.syntax_element_descriptions() return ret_val
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: purpose = self.concept.purpose() sub_sections = [] sub_sections += self._rest_section(purpose) sub_sections += self._see_also_sections(environment) return doc.ArticleContents(docs.paras(purpose.single_line_description), doc.SectionContents([], sub_sections))
def _escape_sequence_table() -> docs.ParagraphItem: def _row(escape_sequence: str, translation: str) -> List[TableCell]: return [ cell(docs.paras(literal_source_text(escape_sequence))), cell(docs.paras(literal_source_text(translation))), ] return docs.first_row_is_header_table( [ [ cell(docs.paras('Source')), cell(docs.paras('Translation')), ]] + [ _row('\\[', '['), _row('\\\\', '\\'), ], ' ')
def invokation_variants(self) -> Sequence[InvokationVariant]: return [ InvokationVariant( _format('{NAME} = {VALUE}'), self._tp.fnap(_DESCRIPTION_OF_SET)), InvokationVariant( _format('unset {NAME}'), paras(_format('Removes the environment variable {NAME}.'))), ]
def initial_paragraphs(self) -> List[ParagraphItem]: command_line = arg.CommandLine([ arg.Single(arg.Multiplicity.MANDATORY, _c(clo.HELP)), arg.Single(arg.Multiplicity.ZERO_OR_MORE, _n('ARGUMENT')) ], prefix=program_info.PROGRAM_NAME) command_line_syntax_text = CommandLineSyntaxRenderer().apply( command_line) return docs.paras(command_line_syntax_text)
def syntax_element_descriptions(self) -> List[SyntaxElementDescription]: actual_file_arg_sed = path_element( _PATH_ARGUMENT.name, ACTUAL_RELATIVITY_CONFIGURATION.options, docs.paras( the_path_of("the directory who's contents is checked."))) return [ actual_file_arg_sed, file_or_dir_contents_doc.get_traversal_options_sed(), ]
def initial_paragraphs(self) -> List[ParagraphItem]: command_line = arg.CommandLine([ arg.Single(arg.Multiplicity.MANDATORY, _c(clo.HELP)), arg.Single(arg.Multiplicity.ZERO_OR_MORE, _n('ARGUMENT'))], prefix=program_info.PROGRAM_NAME) command_line_syntax_text = CommandLineSyntaxRenderer().apply(command_line) return docs.paras(command_line_syntax_text)
def hierarchy(self) -> SectionHierarchyGenerator: initial_paragraphs = paragraphs.constant( docs.paras(_INSTRUCTIONS_IN.format( section_concept=self.section_concept_name, section=self.section.name) )) return h.hierarchy(self.section.syntax_name_text, initial_paragraphs, self._instructions_layout(), )
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: initial_paragraphs = [] invokation_variants = self.syntax_element.invokation_variants() if len(invokation_variants) > 1: initial_paragraphs.append(docs.para(doc_format.text_as_header('Forms:'))) initial_paragraphs += invokation_variants_paragraphs(None, invokation_variants, self.syntax_element.syntax_element_descriptions()) return doc.ArticleContents(docs.paras(self.syntax_element.single_line_description()), doc.SectionContents(initial_paragraphs, self._sub_sections(environment)))
def test_with_non_empty_main_description(self): # ARRANGE # doc = TypeDocumentation(TypeCategory.DATA, A_TYPE_NAME_AND_CROSS_REFERENCE_ID, A_SYNTAX_ELEMENT_INFO, docs.section_contents(docs.paras('initial paragraphs of main description'))) renderer = sut.IndividualTypeConstructor(doc) # ACT # actual = renderer.apply(CONSTRUCTION_ENVIRONMENT) # ASSERT # struct_check.is_article_contents.apply(self, actual)
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: initial_paragraphs = [ self._type_paragraph(), ] sub_sections = description_section_if_non_empty( self.builtin_doc.description) sub_sections += self._see_also_sections(environment) return doc.ArticleContents( docs.paras(self.builtin_doc.single_line_description()), doc.SectionContents(initial_paragraphs, sub_sections))
def _sorted_conf_params_list() -> ParagraphItem: all_cfs = sorted(ALL_CONF_PARAM_INFOS, key=SingularNameAndCrossReferenceId.singular_name.fget) items = [docs.list_item(docs.cross_reference(cf.configuration_parameter_name_text, cf.cross_reference_target, allow_rendering_of_visible_extra_target_text=False), docs.paras(cf.single_line_description_str)) for cf in all_cfs] return lists.HeaderContentList(items, lists.Format(lists.ListType.VARIABLE_LIST, custom_indent_spaces=0, custom_separations=docs.SEPARATION_OF_HEADER_AND_CONTENTS))
def test_with_non_empty_main_description(self): # ARRANGE # for type_cat_case in SYNTAX_ELEM_TYPE_CATEGORY_CASES: doc = TypeDocumentation(A_TYPE_NAME_AND_CROSS_REFERENCE_ID, type_cat_case.value, docs.section_contents(docs.paras('initial paragraphs of main description'))) renderer = sut.IndividualTypeConstructor(doc) with self.subTest(type_cat_case.name): # ACT # actual = renderer.apply(CONSTRUCTION_ENVIRONMENT) # ASSERT # struct_check.is_article_contents.apply(self, actual)
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: purpose = self.conf_param.purpose() sub_sections = [ docs.section('Default Value', [self.conf_param.default_value_para()]) ] sub_sections += self._rest_section(purpose) sub_sections += self._see_also_sections(environment) return doc.ArticleContents(docs.paras(purpose.single_line_description), docs.SectionContents([], sub_sections))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: initial_paragraphs = [] invokation_variants = self.syntax_element.invokation_variants() if len(invokation_variants) > 1: initial_paragraphs.append(headers.FORMS_PARA) initial_paragraphs += invokation_variants_paragraphs( None, invokation_variants, self.syntax_element.syntax_element_descriptions()) return doc.ArticleContents( docs.paras(self.syntax_element.single_line_description()), doc.SectionContents(initial_paragraphs, self._sub_sections(environment)))
def syntax_element_descriptions(self) -> List[SyntaxElementDescription]: return [ rel_path_doc.path_element_2( defs.src_rel_opt_arg_conf_for_phase( False), # TODO -rel-result - see comment below docs.paras( path_syntax.the_path_of_an_existing_file(FileType.REGULAR, final_dot=True)), ( ), # self._tp.fnap(_RELATIVITIES_BEFORE_ACT) TODO -rel-result - see comment below ), self._transformation_sed(), ]
def test_with_main_description_rest_sub_sections(self): description = InstructionDocumentationWithConstantValues( 'instruction name', 'single line description', 'main description rest', [], main_description_rest_sub_sections=[ docs.section('main description rest sub section header', docs.paras('Sub section paragraphs')) ] ) actual = sut.instruction_doc_section_contents_constructor(description).apply(CONSTRUCTION_ENVIRONMENT) struct_check.is_section_contents.apply(self, actual)
def invokation_variants(self) -> List[InvokationVariant]: arguments = path_syntax.mandatory_path_with_optional_relativity( _DST_PATH_ARGUMENT, REL_OPT_ARG_CONF.path_suffix_is_required) contents_arg = a.Single(a.Multiplicity.MANDATORY, a.Named(CONTENTS_ARGUMENT)) assignment_arg = a.Single(a.Multiplicity.MANDATORY, a.Constant(CONTENTS_ASSIGNMENT_TOKEN)) return [ invokation_variant_from_args(arguments, docs.paras('Creates an empty file.')), invokation_variant_from_args(arguments + [assignment_arg, contents_arg], self._tp.paras('Creates a file with contents given by {CONTENTS}.')), ]
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: self.rendering_environment = environment initial_paragraphs = self._default_reporter_info() initial_paragraphs.extend(self.actor.main_description_rest()) sub_sections = [] append_sections_if_contents_is_non_empty( sub_sections, [(self._parser.format('{act_phase} phase contents'), self.actor.act_phase_contents()), (self._parser.format('Syntax of {act_phase} phase contents'), self.actor.act_phase_contents_syntax())]) sub_sections += see_also_sections(self.actor.see_also_targets(), environment) return doc.ArticleContents(docs.paras(self.actor.single_line_description()), doc.SectionContents(initial_paragraphs, sub_sections))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: srd = self.suite_reporter initial_paragraphs = srd.main_description_rest() initial_paragraphs.extend(self._default_reporter_info()) sub_sections = [] names_and_contents = [ ('Output syntax', srd.syntax_of_output()), ('Exit code', srd.exit_code_description()), ] append_sections_if_contents_is_non_empty(sub_sections, names_and_contents) sub_sections += see_also_sections(srd.see_also_targets(), environment) return doc.ArticleContents(docs.paras(srd.single_line_description()), doc.SectionContents(initial_paragraphs, sub_sections))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: documentation = self.documentation sub_sections = [] if documentation.invokation_variants(): sub_sections.append(synopsis_section( invokation_variants_content(documentation.instruction_name(), documentation.invokation_variants(), documentation.syntax_element_descriptions()))) sub_sections += self._main_description_rest_sections() sub_sections += see_also_sections(documentation.see_also_targets(), environment, uppercase_title=True) abstract_paragraphs = docs.paras(self.documentation.single_line_description()) return doc.ArticleContents(abstract_paragraphs, doc.SectionContents([], sub_sections))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: sub_sections = [] if self.doc.invokation_variants(): sub_sections.append(synopsis_section( invokation_variants_content(None, self.doc.invokation_variants(), []))) append_section_if_contents_is_non_empty(sub_sections, 'Description', self.doc.main_description_rest()) sub_sections += see_also_sections(self.doc.see_also_targets(), environment, uppercase_title=True) return doc.ArticleContents(docs.paras(self.doc.single_line_description()), doc.SectionContents([], sub_sections))
def _sorted_conf_params_list() -> ParagraphItem: all_cfs = sorted(ALL_CONF_PARAM_INFOS, key=SingularNameAndCrossReferenceId.singular_name.fget) items = [ docs.list_item( docs.cross_reference( cf.configuration_parameter_name_text, cf.cross_reference_target, allow_rendering_of_visible_extra_target_text=False), docs.paras(cf.single_line_description_str)) for cf in all_cfs ] return lists.HeaderContentList( items, lists.Format( lists.ListType.VARIABLE_LIST, custom_indent_spaces=0, custom_separations=docs.SEPARATION_OF_HEADER_AND_CONTENTS))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: self.rendering_environment = environment initial_paragraphs = self._default_reporter_info() initial_paragraphs.extend(self.actor.main_description_rest()) sub_sections = [] append_sections_if_contents_is_non_empty( sub_sections, [ (self._parser.format('{act_phase} phase contents'), self.actor.act_phase_contents()), (self._parser.format('Syntax of {act_phase} phase contents'), self.actor.act_phase_contents_syntax()), (headers.NOTES__HEADER__CAPITALIZED, self.actor.notes()), ] ) sub_sections += see_also_sections(self.actor.see_also_targets(), environment) return doc.ArticleContents(docs.paras(self.actor.single_line_description()), doc.SectionContents(initial_paragraphs, sub_sections))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: sub_sections = [] if self.doc.invokation_variants(): sub_sections.append( synopsis_section( invokation_variants_content(None, self.doc.invokation_variants(), self.doc.syntax_elements()))) append_section_if_contents_is_non_empty( sub_sections, 'Description', self.doc.main_description_rest()) sub_sections += see_also_sections(self.doc.see_also_targets(), environment, uppercase_title=True) return doc.ArticleContents( docs.paras(self.doc.single_line_description()), doc.SectionContents([], sub_sections))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: documentation = self.documentation sub_sections = [] if documentation.invokation_variants(): sub_sections.append( synopsis_section( invokation_variants_content( documentation.instruction_name(), documentation.invokation_variants(), documentation.syntax_element_descriptions()))) sub_sections += self._main_description_rest_sections() sub_sections += self._outcome() sub_sections += self._notes() sub_sections += see_also_sections(documentation.see_also_targets(), environment, uppercase_title=True) abstract_paragraphs = docs.paras( self.documentation.single_line_description()) return doc.ArticleContents(abstract_paragraphs, doc.SectionContents([], sub_sections))
def section(directory_name: str, dir_info: tcds.TcDirInfo, paragraph_items: List[ParagraphItem]) -> Section: return docs.section( dir_name_text(directory_name), docs.paras(dir_info.single_line_description_str + '.') + paragraph_items)
def _default_value(self) -> Section: return docs.section( 'Default', docs.paras(self._info.default), )
def item_for(syntax: str, description: str) -> lists.HeaderContentListItem: return docs.list_item(syntax_text(syntax), docs.paras(description))
def sequence_info(self) -> PhaseSequenceInfo: return PhaseSequenceInfo(docs.paras('preceding phase'), docs.paras('succeeding phase'), docs.paras('prelude'))
def contents_description(self) -> doc.SectionContents: return docs.section_contents( docs.paras('initial paragraphs') )
def section(directory_name: str, dir_info: tcds.TcDirInfo, paragraph_items: List[ParagraphItem]) -> Section: return docs.section(dir_name_text(directory_name), docs.paras(dir_info.single_line_description_str + '.') + paragraph_items)
def paras( self, s: str, extra: Optional[Mapping[str, Any]] = None, ) -> List[ParagraphItem]: return docs.paras(self.format(s, extra))
def apply(self, environment: ConstructionEnvironment) -> doc.ArticleContents: return doc.ArticleContents(docs.paras('abstract paragraph'), doc.SectionContents(docs.paras('initial paragraph'), []))
def _operator_syntax_element_description() -> SyntaxElementDescription: operators_list = ' '.join(sorted(comparators.NAME_2_OPERATOR.keys())) operator_text = 'One of ' + operators_list return SyntaxElementDescription(OPERATOR_ARGUMENT.name, docs.paras(operator_text))
def execution_environment_info(self) -> ExecutionEnvironmentInfo: return ExecutionEnvironmentInfo( docs.paras('ced_at_start_of_phase'), tuple(docs.paras('prologue')), )
def _default_reporter_info(self) -> list: if self.suite_reporter.singular_name() == DEFAULT_REPORTER.singular_name: return docs.paras('This is the default {reporter_concept}.'.format( reporter_concept=formatting.concept_(SUITE_REPORTER_CONCEPT_INFO))) else: return []
def single_line_description_as_summary_paragraphs( entity_doc: EntityDocumentation) -> List[ParagraphItem]: return docs.paras(entity_doc.single_line_description())
def row(type_name: str, description: str) -> List[TableCell]: return [ docs.cell(docs.paras(doc_format.enum_name_text(type_name))), docs.cell(_TP.fnap(description)), ]