:py:mod:`raesl.doc`
===================

.. py:module:: raesl.doc

.. autoapi-nested-parse::

   ESL to Doc

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



Subpackages
-----------
.. toctree::
   :titlesonly:
   :maxdepth: 3

   locales/index.rst


Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   cli/index.rst
   doc/index.rst
   lines/index.rst
   rich/index.rst
   sections/index.rst
   utils/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   raesl.doc.Doc



Functions
~~~~~~~~~

.. autoapisummary::

   raesl.doc.register_default_locale
   raesl.doc.check_output_path
   raesl.doc.convert



Attributes
~~~~~~~~~~

.. autoapisummary::

   raesl.doc.logger
   raesl.doc.LANGUAGE
   raesl.doc.TITLE
   raesl.doc.OUTPUT
   raesl.doc.PROLOGUE
   raesl.doc.EPILOGUE
   raesl.doc.RICH
   raesl.doc.VARTABLE
   raesl.doc.FORCE
   raesl.doc.DRY


.. py:data:: logger

   

.. py:class:: Doc(*paths: Union[str, pathlib.Path], language: str = 'en', prologue: Optional[pathlib.Path] = None, epilogue: Optional[pathlib.Path] = 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: Optional[str] = 'tex', rich_opts: Optional[Dict[str, Any]] = None, esl_paths: Optional[Union[List[str], List[pathlib.Path]]] = None, **metadata)


   Output document.

   :param paths: ESL input files.
   :param language: Output language.
   :param prologue: Markdown document to include as a prologue.
   :param epilogue: Markdown document to include as a conclusion.
   :param goal_section: Goal section toggle.
   :param transformation_section: Transformation section toggle.
   :param behavior_section: Behavior section toggle.
   :param design_section: Design section toggle.
   :param need_section: Need section toggle.
   :param relation_section: Need section toggle.
   :param var_table: Var table toggle.
   :param rich: Format to create rich output content in, defaults to 'tex'.
   :param rich_opts: Rich output generation options.

   :keyword Document metadata. See pandoc documentation.:

   .. py:property:: as_markdown
      :type: str

      Markdown representation of this document.

   .. py:attribute:: markdown_file_format
      :value: 'markdown+table_captions+multiline_tables+pipe_tables'

      

   .. py:attribute:: markdown_generated
      :value: 'markdown+table_captions+multiline_tables+pipe_tables+grid_tables'

      

   .. py:method:: parse_esl()

      Parse an ESL output Graph


   .. py:method:: yield_markdown() -> Generator[str, None, None]

      Yield markdown lines.


   .. py:method:: yield_metadata() -> Generator[str, None, None]

      Yield metadata lines.


   .. py:method:: yield_pars() -> Generator[str, None, None]

      Yield all paragraph texts.


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

      Save document as a file.

      :param path: Path to save to.
      :param to: Optional format to save to. Normally derived from path.
      :param pandoc_args: Additional arguments for pandoc conversion tool.
      :param filters: Pandoc filters to use.


   .. py:method:: 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.


   .. py:method:: set_var_bundle_roots()

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



.. py:function:: register_default_locale(locale: str = 'en')

   Register default locale if no other locale is set.


.. py:function:: check_output_path(fpath: Union[str, pathlib.Path], force: bool) -> pathlib.Path

   Check output filepath versus force overwrite status.


.. py:data:: LANGUAGE
   :value: 'en'

   

.. py:data:: TITLE
   :value: 'ESL specification'

   

.. py:data:: OUTPUT
   :value: './esl.pdf'

   

.. py:data:: PROLOGUE

   

.. py:data:: EPILOGUE

   

.. py:data:: RICH
   :value: 'tex'

   

.. py:data:: VARTABLE
   :value: True

   

.. py:data:: FORCE
   :value: False

   

.. py:data:: DRY
   :value: False

   

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

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

   :param paths: Paths to resolve into ESL files. May be any number of files and
                 directories to scan.
   :param output: Optional output file (i.e. Markdown, PDF, DOCX).
   :param language: Output document language.
   :param title: Output document title.
   :param prologue: Optional prologue document to include (Markdown).
   :param epilogue: Optional epilogue document to include (Markdown).
   :param var_table: Add table with all variables within appendix.
   :param rich: Format of rich output to use. One of "tex", "md" or "off".
   :param rich_opts: Extra options for selected rich output.
   :param force: Whether to overwrite the output file or raise an error if the file
                 already exists.
   :param dry: Dry run. Skip creating an output document.