Skip to content

Commit 056c832

Browse files
mathiasertlmathiasertl
committed
start a true reference, move other code to how-tos
1 parent 1c34258 commit 056c832

File tree

3 files changed

+225
-201
lines changed

3 files changed

+225
-201
lines changed

‎docs/how-tos.rst‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
##########################
2+
:spelling:ignore:`How-Tos`
3+
##########################
4+
5+
*******
6+
General
7+
*******
8+
9+
Modify the tutorial for documentation or runtime
10+
================================================
11+
12+
Although antithetical to the core promise of this project, sometimes it is unavoidable to run commands
13+
differently from how they are rendered in documentation. Examples are commands that read passwords (and avoid
14+
reading data from stdin):
15+
16+
.. literalinclude:: /tutorials/doc-or-runtime/tutorial.yaml
17+
:language: yaml
18+
19+
This will render as:
20+
21+
.. structured-tutorial:: doc-or-runtime/tutorial.yaml
22+
23+
.. structured-tutorial-part::
24+
25+
... but in reality will run the sudo command to update the password file directly.
26+
27+
****************
28+
Running commands
29+
****************
30+
31+
Test the status code
32+
====================
33+
34+
``structured-tutorials`` will abort a tutorial if a specified command does not exit with a status code of
35+
``0``. To check for a different status code, simply specify ``status_code``:
36+
37+
.. literalinclude:: /tutorials/exit_code/tutorial.yaml
38+
:language: yaml
39+
40+
Cleanup after running a tutorial
41+
================================
42+
43+
To cleanup after after running a tutorial, specify a set of cleanup commands:
44+
45+
.. literalinclude:: /tutorials/cleanup/tutorial.yaml
46+
:language: yaml
47+
48+
Cleanup commands are not rendered in documentation, so this will simply render as:
49+
50+
.. structured-tutorial:: cleanup/tutorial.yaml
51+
52+
.. structured-tutorial-part::
53+
54+
If multiple cleanup commands are specified, they will run in-order. In case of an error, only cleanup commands
55+
for commands that where actually run will be executed. Consider this example:
56+
57+
.. literalinclude:: /tutorials/cleanup-multiple/tutorial.yaml
58+
:language: yaml
59+
60+
Assuming ``cmd1`` and ``cmd2`` run successfully (or ``cmd2`` exits with a non-zero status code), this will
61+
run, in order, ``clean3``, ``clean1`` and ``clean2``. Should ``cmd1`` return a non-zero status code, only
62+
``clean1`` and ``clean2`` will be run.
63+
64+
Test a command
65+
==============
66+
67+
To test if a command is indeed running successfully, use the ``test`` specification. A common use case is a
68+
daemon that will *eventually* open a port, but subsequent commands want to connect to that daemon. For that
69+
reason, you can also simply specify a host and port instead of running a command.
70+
71+
You can also specify a `retry` to run the test command multiple times before the main command is considered
72+
to have failed. A `delay` will delay the first run of the command and a `backoff_factor` will introduce an
73+
increasing delay between retries.
74+
75+
With the following tutorial:
76+
77+
.. literalinclude:: /tutorials/test-command/tutorial.yaml
78+
:language: yaml
79+
80+
The first part will just create a file (and error out if it was not created).
81+
82+
.. structured-tutorial:: test-command/tutorial.yaml
83+
84+
.. structured-tutorial-part::
85+
86+
The second part will test if ``ncat`` is installed and call it after a three-second delay:
87+
88+
.. structured-tutorial-part::
89+
90+
Skip a part at runtime
91+
======================
92+
93+
To skip an entire part at runtime, but still show it in documentation, you can use the ``skip`` configuration:
94+
95+
.. literalinclude:: /tutorials/skip-part-run/tutorial.yaml
96+
:language: yaml
97+
98+
When running the tutorial, only the first part will run:
99+
100+
.. code-block:: console
101+
102+
user@host:~$ structured-tutorial docs/tutorials/skip-part-run/tutorial.yam
103+
+ ls /etc
104+
...
105+
106+
But when generating documentation, both parts will show, for example, this is part one:
107+
108+
.. structured-tutorial:: skip-part-run/tutorial.yaml
109+
110+
.. structured-tutorial-part::
111+
112+
... and this is part two:
113+
114+
.. structured-tutorial-part::
115+
116+
********************
117+
Documenting commands
118+
********************
119+
120+
Show output
121+
===========
122+
123+
To show an output when rendering commands, specify the ``output`` key:
124+
125+
.. literalinclude:: /tutorials/echo/tutorial.yaml
126+
:language: yaml
127+
128+
This will render as:
129+
130+
.. structured-tutorial:: echo/tutorial.yaml
131+
132+
.. structured-tutorial-part::
133+
134+
Template context
135+
================
136+
137+
Both command and output are rendered as template with the current context. The initial context is specified in
138+
the global context, and each command can update the context before and after being shown:
139+
140+
.. literalinclude:: /tutorials/context/tutorial.yaml
141+
:language: yaml
142+
143+
This will render as:
144+
145+
.. structured-tutorial:: context/tutorial.yaml
146+
147+
.. structured-tutorial-part::
148+
149+
150+
Update the command prompt
151+
=========================
152+
153+
To configure the initial command prompt, set below context variables in the initial context. You can update
154+
those variables at any time. The following variables influence the prompt:
155+
156+
prompt
157+
Default: ``"{{ user }}@{{ host }}:{{ cwd }}{% if user == 'root' %}#{% else %}${% endif %} "``
158+
159+
The template used to render the prompt, which includes the values below.
160+
161+
user
162+
Default: ``"user"``
163+
164+
The username rendered in the prompt.
165+
166+
host
167+
Default: ``"host"``
168+
169+
The hostname rendered in the prompt.
170+
171+
cwd
172+
Default: ``"~"``
173+
174+
The current working directory rendered in the prompt.
175+
176+
.. literalinclude:: /tutorials/prompt/tutorial.yaml
177+
:language: yaml
178+
179+
This will render as:
180+
181+
.. structured-tutorial:: prompt/tutorial.yaml
182+
183+
.. structured-tutorial-part::
184+
185+
Skip a part in documentation
186+
============================
187+
188+
To skip an entire part for documentation purposes, but still use it at runtime, you can use the ``skip``
189+
configuration:
190+
191+
.. literalinclude:: /tutorials/skip-part-doc/tutorial.yaml
192+
:language: yaml
193+
194+
When running the tutorial, only the first part will run:
195+
196+
.. code-block:: console
197+
198+
user@host:~$ structured-tutorial docs/tutorials/skip-part-run/tutorial.yaml
199+
+ ls /tmp
200+
...
201+
+ ls /etc
202+
...
203+
204+
But when generating documentation, only the first part can be used. Calling ``structured-tutorial-part`` a
205+
second time will lead to an error (as there are no parts left).
206+
207+
.. structured-tutorial:: skip-part-doc/tutorial.yaml
208+
209+
.. structured-tutorial-part::
210+

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,6 @@ documentation for details.
1616
:caption: Contents:
1717

1818
/quickstart
19+
/how-tos
1920
/reference
2021

0 commit comments

Comments
 (0)