:mod:`snowmobile.core.markup`
=============================

.. py:module:: snowmobile.core.markup

.. autoapi-nested-parse::

   Calling :meth:`script.doc()<snowmobile.core.script.Script.doc()>` returns a
   :class:`Markup` containing a :class:`~snowmobile.core.section.Section` for each
   statement or marker within the script.

   .. note::

       A :class:`Markup` instance, ``m``, returned by
       :meth:`script.doc()<snowmobile.core.script.Script.doc()>`, makes no
       modifications to the sql file read by ``script``

       Instead, ``m`` will generate and export the following two files:

       -   A sql file stripped of all untagged comments, limited to statements
           within the context of ``script`` at the time ``m`` was created
       -   A markdown representation of the code and markup associated with the
           same set of statements

       By default, these files are exported to a ``.snowmobile`` directory
       alongside the sql file that was read by the ``script``; the directory name
       to use for generated exports can be configured in
       :ref:`[script.export-dir-name]<script.export-dir-name>`

       If the target directory does not yet exist, it will be created as part of
       the export process invoked by :meth:`m.save()<Markup.save()>`


   The :ref:`default markdown configuration<script.markdown>` yields a `.md` file
   with the below structure::

           # Script Name.sql         [script name gets an 'h1' header]

           - **Key1**: *Value1*      [keys are bolded, values are italicized]
           - **Key2**: *Value2*      [same for all tags/attributes found]
           - ...

           **Description**           [except for the 'Description' section]
                                     [this is just a blank canvas of markdown..]
                                     [..but this is configurable]

           ## (1) create-table~dummy_name [contents get 'h2' level headers]

           - **Key1**: *Value1*      [identical formatting for st/markers]

           **Description**           [statement descriptions get one of these too]

           **SQL**                   [as does their rendered sql]
               ...sql
                   ...
                   ...
               ...


           ## (2) update-table~dummy_name2

           ...                       [structure repeats for all contents in the script]



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   snowmobile.core.markup.Markup



.. class:: Markup(sn: snowmobile.core.connection.Snowmobile, path: pathlib.Path, contents: Dict[(int, Union[Statement, Marker])], nm: Optional[str] = None, prefix: Optional[str] = None, suffix: Optional[str] = None, root_dir: Optional[Union[str, Path]] = None, sub_dir: Optional[str] = None, incl_sql: bool = True, incl_markers: bool = True, incl_sql_tag: bool = False, incl_exp_ctx: bool = True, result_wrap: Optional[str] = None)


   Bases: :class:`snowmobile.core.Generic`

   Contains all sections within the context of a :class:`~snowmobile.Script`.

   :param sn: A :class:`~snowmobile.Snowmobile` instance.
   :type sn: Snowmobile
   :param path: A full path to the sql file that script was instantiated from.
   :type path: Path
   :param contents: A dictionary of the script's contents (st and markers) by
                    index position.
   :type contents: Dict[int, Union[Statement, Marker]]
   :param nm: Alternate file name to use; defaults to ``path.name``.
   :type nm: Optional[str]
   :param prefix: Prefix to prepend to original file name when exporting.
   :type prefix: Optional[str]
   :param suffix: Suffix to append to original file name when exporting.
   :type suffix: Optional[str]
   :param root_dir: Alternate target directory for exports; defaults to
                    ``./.snowmobile`` where ``.`` is the directory containing the sql
                    file that the ``script`` was created from.
   :type root_dir: Optional[Union[str, Path]]
   :param sub_dir: Alternate sub-directory name; defaults to ``path.name`` where
                   ``path`` is a full :class:`~pathlib.Path` to the sql file that the
                   ``script`` was created from.
   :type sub_dir: Optional[str]
   :param incl_sql: Include statements in export.
   :type incl_sql: bool
   :param incl_markers: Include markers in export.
   :type incl_markers: bool
   :param incl_sql_tag: Include the raw wrap in the sql that is rendered in the `md` export.
   :type incl_sql_tag: bool
   :param incl_exp_ctx: Include (configurable) disclaimer at the top of exported `sql` file.
   :type incl_exp_ctx: bool

   .. attribute:: exported

      List of file paths that current instance has exported to.

      :type: List[Path]

   .. attribute:: created

      List of directory paths that current instance has created (should
      mostly apply for initial scaffolding build on first run only).

      :type: List[Path]

   .. method:: export_dir(self) -> pathlib.Path
      :property:

      Documentation sub-directory; `.snowmobile` by default.


   .. method:: sections(self) -> Dict[(int, Section)]
      :property:

      Dictionary of all :class:`sections<snowmobile.core.Section>` by index position.


   .. method:: markdown(self) -> str
      :property:

      Full markdown file as a string.


   .. method:: sql(self)
      :property:

      SQL for save.


   .. method:: save(self, md: bool = True, sql: bool = True) -> None

      Save files to disk.

      :param md: Export a generated markdown file.
      :type md: bool
      :param sql: Export a generated sql file.
      :type sql: bool