raesl.doc

ESL to Doc

A Python package to process specifications in the form of .esl files into regular document formats such as .pdf.

Subpackages

• raesl.doc.locales
  • raesl.doc.locales.en
  • raesl.doc.locales.nl

Submodules

• raesl.doc.cli
• raesl.doc.doc
• raesl.doc.lines
• raesl.doc.rich
• raesl.doc.sections
• raesl.doc.utils

Package Contents

Classes

Doc	Output document.

Functions

register_default_locale([locale])	Register default locale if no other locale is set.
check_output_path(→ pathlib.Path)	Check output filepath versus force overwrite status.
convert(*paths[, output, language, title, prologue, ...])	Convert ESL files and/or directories to a formatted document.

Attributes

logger
LANGUAGE
TITLE
OUTPUT
PROLOGUE
EPILOGUE
RICH
VARTABLE
FORCE
DRY

raesl.doc.logger

class raesl.doc.Doc(*paths: str | pathlib.Path, language: str = 'en', prologue: pathlib.Path | None = None, epilogue: pathlib.Path | None = None, goal_section: [bool] = True, transformation_section: [bool] = True, behavior_section: [bool] = True, design_section: [bool] = True, need_section: [bool] = True, relation_section: [bool] = True, var_table: [bool] = True, rich: str | None = 'tex', rich_opts: Dict[str, Any] | None = None, esl_paths: List[str] | List[pathlib.Path] | None = None, **metadata)

Output document.

Parameters:

• paths – ESL input files.

• language – Output language.

• prologue – Markdown document to include as a prologue.

• epilogue – Markdown document to include as a conclusion.

• goal_section – Goal section toggle.

• transformation_section – Transformation section toggle.

• behavior_section – Behavior section toggle.

• design_section – Design section toggle.

• need_section – Need section toggle.

• relation_section – Need section toggle.

• var_table – Var table toggle.

• rich – Format to create rich output content in, defaults to ‘tex’.

• rich_opts – Rich output generation options.

Keyword Arguments:

documentation. (Document metadata. See pandoc) –

property as_markdown: str

Markdown representation of this document.

markdown_file_format = 'markdown+table_captions+multiline_tables+pipe_tables'

markdown_generated = 'markdown+table_captions+multiline_tables+pipe_tables+grid_tables'

parse_esl()

Parse an ESL output Graph

yield_markdown() → Generator[str, None, None]

Yield markdown lines.

yield_metadata() → Generator[str, None, None]

Yield metadata lines.

yield_pars() → Generator[str, None, None]

Yield all paragraph texts.

save(path: pathlib.Path | str, to: str | None = None, pandoc_args: List[str] = ['--standalone', '--number-sections', '--toc', '--listings', '--self-contained'], filters: List[str] = ['pandoc-fignos'])

Save document as a file.

Parameters:

• path – Path to save to.

• to – Optional format to save to. Normally derived from path.

• pandoc_args – Additional arguments for pandoc conversion tool.

• filters – Pandoc filters to use.

get_bundle_name_parts() → Set[str]

Get set of all name parts of bundles used within the spec

Returns:

Set of all name parts of bundles.

set_var_bundle_roots()

Set the bundle root of variables if they originate from a bundle.

raesl.doc.register_default_locale(locale: str = 'en')

Register default locale if no other locale is set.

raesl.doc.check_output_path(fpath: str | pathlib.Path, force: bool) → pathlib.Path

Check output filepath versus force overwrite status.

raesl.doc.LANGUAGE = 'en'

raesl.doc.TITLE = 'ESL specification'

raesl.doc.OUTPUT = './esl.pdf'

raesl.doc.PROLOGUE

raesl.doc.EPILOGUE

raesl.doc.RICH = 'tex'

raesl.doc.VARTABLE = True

raesl.doc.FORCE = False

raesl.doc.DRY = False

raesl.doc.convert(*paths: str | pathlib.Path, output: str | pathlib.Path = OUTPUT, language: str = LANGUAGE, title: str = TITLE, prologue: str | pathlib.Path | None = PROLOGUE, epilogue: str | pathlib.Path | None = EPILOGUE, var_table: bool = VARTABLE, rich: str | None = RICH, rich_opts: Dict[str, Any] | None = None, force: bool = FORCE, dry: bool = DRY, **metadata)

Convert ESL files and/or directories to a formatted document.

Parameters:

• paths – Paths to resolve into ESL files. May be any number of files and directories to scan.

• output – Optional output file (i.e. Markdown, PDF, DOCX).

• language – Output document language.

• title – Output document title.

• prologue – Optional prologue document to include (Markdown).

• epilogue – Optional epilogue document to include (Markdown).

• var_table – Add table with all variables within appendix.

• rich – Format of rich output to use. One of “tex”, “md” or “off”.

• rich_opts – Extra options for selected rich output.

• force – Whether to overwrite the output file or raise an error if the file already exists.

• dry – Dry run. Skip creating an output document.