##########################
:spelling:ignore:`How-Tos`
##########################

*******
General
*******

Modify the tutorial for documentation or runtime
================================================

Although antithetical to the core promise of this project, sometimes it is unavoidable to run commands
differently from how they are rendered in documentation. Examples are commands that read passwords (and avoid
reading data from stdin):

.. literalinclude:: /tutorials/doc-or-runtime/tutorial.yaml
    :language: yaml

This will render as:

.. structured-tutorial:: doc-or-runtime/tutorial.yaml

.. structured-tutorial-part::

... but in reality will run the sudo command to update the password file directly.

****************
Running commands
****************

Test for installed tools
========================

You can specify a list of tools that is required for running the tutorial. ``structured-tutorials`` will then
test if a certain tool is installed before starting the tutorial and present the user with a nice error
message:

.. literalinclude:: /tutorials/required_executables/tutorial.yaml
    :language: yaml

.. structured-tutorial:: required_executables/tutorial.yaml

.. structured-tutorial-part::

Cleanup after running a tutorial
================================

To cleanup after after running a tutorial, specify a set of cleanup commands:

.. literalinclude:: /tutorials/cleanup/tutorial.yaml
    :language: yaml

Cleanup commands are not rendered in documentation, so this will simply render as:

.. structured-tutorial:: cleanup/tutorial.yaml

.. structured-tutorial-part::

If multiple cleanup commands are specified, they will run in-order. In case of an error, only cleanup commands
for commands that where actually run will be executed. Consider this example:

.. literalinclude:: /tutorials/cleanup-multiple/tutorial.yaml
    :language: yaml

Assuming ``cmd1`` and ``cmd2`` run successfully (or ``cmd2`` exits with a non-zero status code), this will
run, in order, ``clean3``, ``clean1`` and ``clean2``. Should ``cmd1`` return a non-zero status code, only
``clean1`` and ``clean2`` will be run.


Skip a part at runtime
======================

To skip an entire part at runtime, but still show it in documentation, simply set ``run: false``:

.. literalinclude:: /tutorials/skip-part-run/tutorial.yaml
    :language: yaml

When running the tutorial, only the first part will run:

.. code-block:: console

    user@host:~$ structured-tutorial docs/tutorials/skip-part-run/tutorial.yam
    + ls /etc
    ...

But when generating documentation, both parts will show, for example, this is part one:

.. structured-tutorial:: skip-part-run/tutorial.yaml

.. structured-tutorial-part::

... and this is part two:

.. structured-tutorial-part::

********************
Documenting commands
********************

Show output
===========

To show an output when rendering commands, specify the ``output`` key:

.. literalinclude:: /tutorials/echo/tutorial.yaml
    :language: yaml

This will render as:

.. structured-tutorial:: echo/tutorial.yaml

.. structured-tutorial-part::

Template context
================

Both command and output are rendered as template with the current context. The initial context is specified in
the global context, and each command can update the context before and after being shown:

.. literalinclude:: /tutorials/context/tutorial.yaml
    :language: yaml

This will render as:

.. structured-tutorial:: context/tutorial.yaml

.. structured-tutorial-part::


Update the command prompt
=========================

To configure the initial command prompt, set below context variables in the initial context. You can update
those variables at any time. The following variables influence the prompt:

prompt
    Default: ``"{{ user }}@{{ host }}:{{ cwd }}{% if user == 'root' %}#{% else %}${% endif %} "``

    The template used to render the prompt, which includes the values below.

user
    Default: ``"user"``

    The username rendered in the prompt.

host
    Default: ``"host"``

    The hostname rendered in the prompt.

cwd
    Default: ``"~"``

    The current working directory rendered in the prompt.

.. literalinclude:: /tutorials/prompt/tutorial.yaml
    :language: yaml

This will render as:

.. structured-tutorial:: prompt/tutorial.yaml

.. structured-tutorial-part::

Skip a part in documentation
============================

To skip an entire part for documentation purposes, but still use it at runtime, you can use the ``skip``
configuration:

.. literalinclude:: /tutorials/skip-part-doc/tutorial.yaml
    :language: yaml

When running the tutorial, only the first part will run:

.. code-block:: console

    user@host:~$ structured-tutorial docs/tutorials/skip-part-run/tutorial.yaml
    + ls /tmp
    ...
    + ls /etc
    ...

But when generating documentation, only the first part can be used. Calling ``structured-tutorial-part`` a
second time will lead to an error (as there are no parts left).

.. structured-tutorial:: skip-part-doc/tutorial.yaml

.. structured-tutorial-part::