def purpose(self) -> DescriptionWithSubSections:
tp = TextParser({
'cd_concept': formatting.concept(self.singular_name()),
'CD': self.acronym(),
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'sds_concept': formatting.concept_(concepts.SDS_CONCEPT_INFO),
'act_sub_dir': SUB_DIRECTORY__ACT + '/',
'path_type': formatting.symbol_type_(types.PATH_TYPE_INFO),
'act_phase': phase_names.ACT.emphasis,
'rel_cd_option': formatting.cli_option(path.REL_CWD_OPTION),
'cd_instruction': InstructionName(instruction_names.CHANGE_DIR_INSTRUCTION_NAME),
'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME),
'instruction': concepts.INSTRUCTION_CONCEPT_INFO.name,
'os_process': misc_texts.OS_PROCESS_NAME,
})
return DescriptionWithSubSections(
self.single_line_description(),
SectionContents(
tp.fnap(_INITIAL_PARAGRAPHS),
[
docs.section(
tp.text(_USING_THE_CD_HEADER),
tp.fnap(_USING_THE_CD)
),
docs.section(
tp.text(_DESCRIPTION_DEF_INSTRUCTION_HEADER),
cd_instruction_section_on_def_instruction()
),
]
))
def main_description_rest_sub_sections(self) -> List[SectionItem]:
return [
docs.section(misc_texts.RELATIVITY.singular.capitalize(),
self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY),
[docs.section(headers.NOTES__HEADER__CAPITALIZED,
self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY_NOTE))]),
path_type_path_rendering()
]
def main_description_rest_sub_sections(self) -> List[SectionItem]:
return [
docs.section('Relativity',
self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY),
[docs.section('NOTE',
self._parser.fnap(_MAIN_DESCRIPTION_RELATIVITY_NOTE))]),
path_type_path_rendering()
]
def purpose(self) -> DescriptionWithSubSections:
rest_paragraphs = self._parser.fnap(_REST_DESCRIPTION)
sub_sections = [
docs.section('Definition', self._parser.fnap(_DEFINITION)),
docs.section('Reference', self._reference_paragraphs()),
]
return DescriptionWithSubSections(
self.single_line_description(),
SectionContents(rest_paragraphs, sub_sections))
def purpose(self) -> DescriptionWithSubSections:
return DescriptionWithSubSections(
self.single_line_description(),
docs.section_contents(self._tp.fnap(_DESCRIPTION_REST), [
docs.section('Semantics', self._tp.fnap(_SEMANTICS)),
docs.section(
'Syntax',
[FORMS_PARA] + self._invokation_variants_paragraphs() +
self._tp.fnap(_SYNTAX),
),
]))
def notes(self) -> SectionContents:
return docs.section_contents(sub_sections=[
docs.section(
self._tp.text('{path:/u} {relativity:s}'),
self._notes_section_paragraphs(),
),
docs.section(
self._tp.text(misc_texts.STDIN.capitalize()),
self._tp.fnap(_STDIN_DESCRIPTION),
),
docs.section(
self._tp.text('Transformations'),
self._tp.fnap(_TRANSFORMATION_DESCRIPTION),
),
])
def _rest_section(purpose: DescriptionWithSubSections):
rest = purpose.rest
if rest.is_empty:
return []
sect = docs.section('Description', rest.initial_paragraphs,
rest.sections)
return [sect]
def _rest_section(purpose: DescriptionWithSubSections):
rest = purpose.rest
if rest.is_empty:
return []
sect = docs.section('Description',
rest.initial_paragraphs,
rest.sections)
return [sect]
def _rest_section(purpose: DescriptionWithSubSections):
rest = purpose.rest
if rest.is_empty:
return []
sect = docs.section(DESCRIPTION__HEADER__CAPITALIZED,
rest.initial_paragraphs,
rest.sections)
return [sect]
def contents_description(self) -> SectionContents:
tp = TextParser({
'default_suite_file_name':
file_names.DEFAULT_SUITE_FILE,
})
return docs.section_contents(
path_contents_description('suite'),
[docs.section('Default suite file', tp.fnap(_DIR_AS_SUITE))])
def _options_sections(
self, argument_descriptions: List[DescribedArgument]
) -> List[docs.Section]:
if not argument_descriptions:
return []
option_paragraphs = self._list(
map(self._arg_description_list_item, argument_descriptions))
return [docs.section('OPTIONS', [option_paragraphs])]
def _add_section_for_environment(self, output: List[docs.SectionItem]):
list_items = []
list_items += self._current_directory_items()
list_items += self._environment_variables_items()
list_items += self._timeout_items()
list_items += self.doc.execution_environment_info().custom_items
if list_items:
properties_list = docs.simple_list_with_space_between_elements_and_content(
list_items, lists.ListType.ITEMIZED_LIST)
output.append(docs.section('Environment', [properties_list]))
def _add_section_for_environment(self, output: List[docs.SectionItem]):
list_items = []
list_items += self._current_directory_items()
list_items += self._environment_variables_items()
list_items += self.doc.execution_environment_info().custom_items
if list_items:
properties_list = docs.simple_list_with_space_between_elements_and_content(list_items,
lists.ListType.ITEMIZED_LIST)
output.append(docs.section('Environment',
[properties_list]))
def contents_description(self) -> SectionContents:
tp = TextParser({
'default_suite_file_name': file_names.DEFAULT_SUITE_FILE,
})
return docs.section_contents(
file_ref_contents_description('suite'),
[
docs.section('Default suite file',
tp.fnap(_DIR_AS_SUITE))
]
)
def purpose(self) -> DescriptionWithSubSections:
rest_paragraphs = self._parser.fnap(_REST__BEFORE_CATEGORY_LIST)
rest_paragraphs.append(_types_categories_list(self._parser))
rest_paragraphs += (self._parser.fnap(_REST__AFTER_CATEGORY_LIST))
sub_sections = [
docs.section(self._parser.text('Summary of {type:s}'),
[_types_list()])
]
return DescriptionWithSubSections(
self.single_line_description(),
SectionContents(rest_paragraphs, sub_sections))
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.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 outcome(
self, environment: ConstructionEnvironment
) -> Optional[docs.SectionContents]:
paragraphs = case_outcome_help.TEXT_PARSER.fnap(
case_outcome_help.REPORTING)
paragraphs += _TP.fnap(_OUTCOME_INITIAL_PARAGRAPHS_EXTRA)
paragraphs += exit_invalid_usage.paragraphs()
return docs.section_contents(paragraphs, [
docs.section(
case_outcome_help.ALL_EXIT_VALUES_SUMMARY_TABLE_HEADER,
[case_outcome_help.all_exit_values_summary_table()])
])
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 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 purpose(self) -> DescriptionWithSubSections:
return DescriptionWithSubSections(
self.single_line_description(),
docs.section_contents(
self._tp.fnap(_INITIAL_PARAGRAPHS),
[
docs.section(self._tp.text('Environment variables set by {program_name}'),
self._tp.fnap(_E_SETS_EXTRA_ENV_VARS),
[
self._variables_from_setup(),
self._variables_from_before_assert(),
])
]))
def purpose(self) -> DescriptionWithSubSections:
tp = TextParser({
'cd_concept': formatting.concept(self.singular_name()),
'CD': self.acronym(),
'program_name': formatting.program_name(program_info.PROGRAM_NAME),
'sds_concept': formatting.concept_(concepts.SANDBOX_CONCEPT_INFO),
'act_sub_dir': SUB_DIRECTORY__ACT + '/',
'path_type': formatting.symbol_type_(types.PATH_TYPE_INFO),
'act_phase': phase_names.ACT.syntax,
'rel_cd_option': formatting.cli_option(file_ref.REL_CWD_OPTION),
'cd_instruction': InstructionName(instruction_names.CHANGE_DIR_INSTRUCTION_NAME),
'run_instruction': InstructionName(instruction_names.RUN_INSTRUCTION_NAME),
'shell_instruction': InstructionName(instruction_names.SHELL_INSTRUCTION_NAME),
'def_instruction': InstructionName(instruction_names.SYMBOL_DEFINITION_INSTRUCTION_NAME),
'os_process': misc_texts.OS_PROCESS_NAME,
})
return DescriptionWithSubSections(
self.single_line_description(),
SectionContents(
tp.fnap(_INITIAL_PARAGRAPHS),
[
docs.section(
tp.text(_USING_THE_CD_HEADER),
tp.fnap(_USING_THE_CD)
),
docs.section(
tp.text(_DESCRIPTION_DEF_INSTRUCTION_HEADER),
cd_instruction_section_on_def_instruction()
),
]
))
def purpose(self) -> DescriptionWithSubSections:
sub_sections = [
self._tp.section(
concepts.CONFIGURATION_PARAMETER_CONCEPT_INFO.plural_name.
capitalize(), _CONFIGURATION_PARAMETER),
self._tp.section('Relative paths', _RELATIVITY),
self._tp.section(
self._tp.format(
BUILTIN_SYMBOL_ENTITY_TYPE_NAMES.name.plural.capitalize()),
_BUILTIN_SYMBOL),
docs.section('Directories', self._directory_listing()),
]
return DescriptionWithSubSections(
self.single_line_description(),
SectionContents(self._tp.fnap(_MAIN_DESCRIPTION_REST),
sub_sections))
def _sandbox_directories_info_sections(self) -> List[docs.SectionItem]:
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)
return [
section(sds.SUB_DIRECTORY__ACT, tcds.SDS_ACT_INFO,
self._act_dir_description_paragraphs()),
section(sds.SUB_DIRECTORY__RESULT, tcds.SDS_RESULT_INFO,
self._result_dir_description_paragraphs()),
section(sds.PATH__TMP_USER, tcds.SDS_TMP_INFO,
self._tmp_user_dir_description_paragraphs()),
docs.section(dir_name_text(sds.SUB_DIRECTORY__INTERNAL),
self._internal_dir_description_paragraphs())
]
def _sandbox_directories_info_sections(self) -> List[docs.SectionItem]:
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)
return [
section(sds.SUB_DIRECTORY__ACT,
tcds.SDS_ACT_INFO,
self._act_dir_description_paragraphs()),
section(sds.SUB_DIRECTORY__RESULT,
tcds.SDS_RESULT_INFO,
self._result_dir_description_paragraphs()),
section(sds.PATH__TMP_USER,
tcds.SDS_TMP_INFO,
self._tmp_user_dir_description_paragraphs()),
docs.section(dir_name_text(sds.SUB_DIRECTORY__INTERNAL),
self._internal_dir_description_paragraphs())
]
def runTest(self):
for type_category in [None, TypeCategory.DATA]:
nrt = name_and_ref_target('SE1', type_category,
'single line description of SE1')
test_cases = [
('minimal',
syntax_element_documentation(nrt.type_category, nrt, [], (),
[], [], [])),
('with main description rest',
syntax_element_documentation(nrt.type_category, nrt,
[docs.para('a paragraph')], (),
[], [], [])),
('with main description rest sub sections',
syntax_element_documentation(nrt.type_category, nrt, [], [
docs.section('a section header',
docs.paras('section contents'))
], [], [], [])),
('with main description rest, and notes',
syntax_element_documentation(
nrt.type_category,
nrt,
[],
[
docs.section('a section header',
docs.paras('section contents'))
],
[],
[],
[],
docs.section_contents(
docs.paras('notes section contents')),
)),
('with invokation variants',
syntax_element_documentation(nrt.type_category, nrt, [], (),
syntax_parts.INVOKATION_VARIANTS,
[], [])),
('with syntax element descriptions',
syntax_element_documentation(
nrt.type_category, nrt, [], (), [],
syntax_parts.SYNTAX_ELEMENT_DESCRIPTIONS, [])),
('see also',
syntax_element_documentation(
nrt.type_category,
nrt,
[],
(),
[],
[],
[CustomCrossReferenceId('custom-target-name')],
)),
('full',
syntax_element_documentation(
nrt.type_category, nrt, [docs.para('a paragraph')], [
docs.section('a section header',
docs.paras('section contents'))
],
[InvokationVariant('syntax', [docs.para('a paragraph')])],
syntax_parts.SYNTAX_ELEMENT_DESCRIPTIONS,
[CustomCrossReferenceId('custom-target-name')],
docs.section_contents(
docs.paras('notes section contents')))),
]
for test_case_name, documentation in test_cases:
with self.subTest(test_case_name=test_case_name,
type_category=type_category):
# ARRANGE #
renderer = sut.IndividualSyntaxElementConstructor(
documentation)
# ACT #
actual = renderer.apply(CONSTRUCTION_ENVIRONMENT)
# ASSERT #
struct_check.is_article_contents.apply(self, actual)
def _sections():
return [docs.section('header', _paragraphs())]
def directory_structure_list_section(dir_with_sub_dir_list: List[DirWithSubDirs]) -> Section:
return docs.section('Directory structure',
[_directory_structure_list(dir_with_sub_dir_list)])
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 apply(self, environment: ConstructionEnvironment) -> doc.SectionContents:
return doc.SectionContents(self._tp.fnap(_INITIAL_DESCRIPTION),
[
docs.section('File structure',
self._tp.fnap(_FILE_STRUCTURE))
])
def outcome(self, environment: ConstructionEnvironment) -> Optional[docs.SectionContents]:
paragraphs = case_outcome_help.TEXT_PARSER.fnap(case_outcome_help.REPORTING)
paragraphs += _TP.fnap(_OUTCOME_INITIAL_PARAGRAPHS_EXTRA)
return docs.section_contents(paragraphs,
[docs.section(case_outcome_help.ALL_EXIT_VALUES_SUMMARY_TABLE_HEADER,
[case_outcome_help.all_exit_values_summary_table()])])
def directory_structure_list_section(
dir_with_sub_dir_list: List[DirWithSubDirs]) -> Section:
return docs.section('Directory structure',
[_directory_structure_list(dir_with_sub_dir_list)])
def _sections():
return [docs.section('header', _paragraphs())]
def _variables_section(first_phase_name: formatting.SectionName,
paragraphs: List[docs.ParagraphItem]) -> docs.Section:
return docs.section(
'Variables available in {first_phase_name} and later phases'.format(first_phase_name=first_phase_name.syntax),
paragraphs)
def _section(self, header: str, text_to_format: str) -> docs.Section:
return docs.section(header,
self._tp.fnap(text_to_format))
def apply(self,
environment: ConstructionEnvironment) -> doc.SectionContents:
return doc.SectionContents(
self._tp.fnap(_INITIAL_DESCRIPTION),
[docs.section('File structure', self._tp.fnap(_FILE_STRUCTURE))])
def _add_section_for_phase_sequence_description(
self, output: List[docs.SectionItem]):
si = self.doc.sequence_info()
output.append(
docs.section('Phase execution order', si.prelude +
si.preceding_phase + si.succeeding_phase))
def _default_value(self) -> Section:
return docs.section(
'Default',
docs.paras(self._info.default),
)
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 _add_section_for_phase_sequence_description(self, output: List[docs.SectionItem]):
si = self.doc.sequence_info()
output.append(docs.section('Phase execution order',
si.prelude + si.preceding_phase + si.succeeding_phase))
def _options_sections(self, argument_descriptions: List[DescribedArgument]) -> List[docs.Section]:
if not argument_descriptions:
return []
option_paragraphs = self._list(map(self._arg_description_list_item, argument_descriptions))
return [docs.section('OPTIONS', [option_paragraphs])]