Supported Parameters¤

Except when otherwise noted, these parameters can be given - per environment - per page - per block and - per statement

They work in session or non session mode.

Syntax details here.

Parameter Support

Note that most but not all parameters do make sense for all plugins, e.g. prompt.

The ones listed are all supported for bash shell mode.
The session specific params make sense only for plugins which do support sessions (bash, python)

addsrc / addsrc=`<fmt|title>`¤

(boolean or source format or title)

Adds the lp source into the rendered page

All examples on this page use that header, set on page level.

See AddSrcFormats regarding available formats.

When you say addsrc=<a string> then we'll use format number 4 and set that string as the title.

Example:

 ```bash lp addsrc=Example fmt=mk_console
 ls /etc | head -n 3
 ```

Renders:

Example

$ ls /etc | head -n 3
adduser.conf
alternatives
apache2

Source

 
 ```bash lp addsrc=Example fmt=mk_console
 ls /etc | head -n 3
 ```

asserts¤

asserts=<match string or condition>

Raises an exception, if the expected string is not found in the result of an evaluation.

Via this you can use LP as an (additional) functional test suite (and avoid broken docu).

You may specify a single string or a pycond expression.

bash lp asserts dwrx or
bash lp asserts=['root', 'dwrx'] or even
`bash lp asserts='[root and dwrx] and not fubar' (see here for valid expressions)

Your docu build will exit with error on an assertion failure.

Example

LP Source:

 ```bash lp asserts=etc
 ls /
 # statement specific assertion:
 echo hi # lp: asserts="hi and not [bar or etc]"
 ```

Result:

Cmd

$ ls /
$ # statement specific assertion:
$ echo hi

Output

$ ls /
bin
boot
data
dev
etc
home
imagegeneration
lib
lib32
lib64
libx32
lost+found
media
mnt
opt
proc
root
run
sbin
snap
srv
sys
tmp
usr
var
$ # statement specific assertion:

$ echo hi
hi

As you can see, if given at block level all results of all evaluations of the block are matched.

body¤

body=<lp body string>

Provides the body of the LP statement

If you only have a short body you may use the short form and provide it within the header using that parameter.

Caution

If you have a real body as well and it is a string, then we will prefix it with this header value.

Example

LP Source (shortform):

 `lp:bash cwd='/etc', asserts='hosts', body='ls . | grep host'`

Result:

Cmd

$ ls . | grep host

Output

$ ls . | grep host
host.conf
hostname
hosts
hosts.allow
hosts.deny

cwd¤

cwd=<directory>

change directory before running the command

Example

LP Source:

 ```bash lp cwd=/etc asserts=hosts
 ls  . | grep hosts
 ```

Result:

Cmd

$ ls  . | grep hosts

Output

$ ls  . | grep hosts
hosts
hosts.allow
hosts.deny

eval¤

eval=<never|always|on_change|on_page_change|<page match[:block match]>

Determines which blocks to evaluate at mkdocs build or mkdocs serve

Please see the specific chapter about eval.

expect¤

expect=<match string or condition> or False

Wait for this string to show up in the output

Makes no much sense in singleshot mode, where we simply run commands, until they complete. In singleshot mode use asserts to fail if an expected result is not showing up.
Useful e.g. when, within sessions, a command blocks forever. As soon as the string occurs within the output, we stop listening and return as result what we have seen so far.
If set to False then all we stop collecting results when timeout is reached (no timeout error then).

Warning

If the session is not stopped or Ctrl-C is sent (see example), then the command will be running even after mkdocs build.

Example

We set to False, causing evaluation to stop after the timeout - otherwise this would run forever:

LP Source:

 ```bash lp timeout=0.1 session=test
 while true; do date; sleep 0.05; done # lp: expect=false
 send-keys: C-c # we will reuse that session, so we send ctrl-c
 ```

Result:

Cmd

$ while true; do date; sleep 0.05; done

Output

runner@fv-az135-986:~/work/docutools/docutools$ while true; do date; sleep 0.05; done               
Mon 04 Oct 2021 09:03:19 PM UTC         
Mon 04 Oct 2021 09:03:19 PM UTC         
Mon 04 Oct 2021 09:03:19 PM UTC

fetch¤

fetch=<use_case_name>

Async Result Fetching from Server

The evaluation output content is fetched after page load as soon as the user clicks on the output tab. This significantly improves pages load times, when there is a lot of output.

Example

LP Source:

 ```bash lp session=test fetch=async_example
 ls -lt /usr/bin | head -n 12
 ```

Result:

Cmd

$ ls -lt /usr/bin | head -n 12

Output

 remote_content

Here is more about the mechanics.

fmt¤

fmt=<mk_console|mk_cmd_out|xt_flat>

Determines Markdown Representation of Results

mk_cmd_out: Displays two tabs, with command and output
xt_flat: Command and output in one go, xterm formatted ANSI escape codes
mk_console: An mkdocs console fenced code statement is produced, no ANSI escape formatting by xterm (the command is highlighted by mkdocs).

xt_flat output must be visible at page load

Due to a technical restriction you currently cannot hide embedded or fetched xt_flat output within closed admonitions. You may use ???+ note "title" style closeable admonitions though.

Default is mk_cmd_out

Examples

mk_console

LP Source:

 ```bash lp fmt=mk_console
 echo Hello
 ```

Result:

$ echo Hello
Hello

xt_flat

LP Source:

 ```bash lp fmt=xt_flat
 echo Hello
 ```

Result:

$ echo Hello
Hello

mk_cmd_out

LP Source:

 ```bash lp fmt=mk_cmd_out
 echo Hello
 ```

Result:

Cmd

$ echo Hello

Output

$ echo Hello
Hello

Custom Formats

Plugins can also decide to deliver their own formatted markdown.

hide_cmd¤

(boolean)

When set to True then command itself wont' be displayed.

Currently this is only supported in singleshot mode.

Example

LP Source:

 ```bash lp cwd=/etc hide_cmd
 ls . | grep hosts
 ```

Result:

hosts
hosts.allow
hosts.deny

kill_session¤

(boolean)

When set to True then the session will be killed after evaluation

By definition, this is only supported in session mode.

Example

LP Source:

 ```bash lp kill_session session=kill_test
 tmux list-sessions | grep kill_test
 ls . | grep hosts
 ```

Result:

Cmd

$ tmux list-sessions | grep kill_test
$ ls . | grep hosts

Output

$ tmux list-sessions | grep kill_test                 
kill_test: 1 windows (created Mon Oct  4 21:03:20 2021)
$ ls . | grep hosts

LP Source:

 ```bash lp asserts="not kill_test"
 tmux list-sessions | grep test || true
 ```

Result:

Cmd

$ tmux list-sessions | grep test || true

Output

$ tmux list-sessions | grep test || true
docutest: 1 windows (created Mon Oct  4 21:03:02 2021)
dt_test: 1 windows (created Mon Oct  4 21:03:05 2021)
nodejs_test: 1 windows (created Mon Oct  4 21:03:03 2021)
test: 1 windows (created Mon Oct  4 21:03:19 2021)
test1: 1 windows (created Mon Oct  4 21:02:54 2021)

mode¤

mode=<plugin name> or <lang> lp:<mode>

Pass evaluation into various plugins

See here for a list of included plugins.
The value "page" is a special mode, not specifying a plugin but setting the following header parameters page wide for all blocks as defaults. Example:

lp:page timeout=20 (short form used)

new_session¤

new_session=<tmux session name>

Runs the block within a new tmux session

If the session already exists, it will be destroyed before running.

Example

LP Source:

 ```bash lp new_session=docutest
 date
 tmux list-sessions | grep docutest
 ```

Result:

Cmd

$ date
$ tmux list-sessions | grep docutest

Output

$ date        
Mon 04 Oct 2021 09:03:20 PM UTC
$ tmux list-sessions | grep docutest                  
docutest: 1 windows (created Mon Oct  4 21:03:20 2021)

Here is more about sessions.

pdb¤

(boolean)

Enter debug mode before and after evaluation

Example

 ```bash lp pdb
 ls .
 ```

The execution will be halted and you get the chance to inspect variables and step through the code.

post¤

post=<some command>

Runs something after the (output recorded) commands

Examples

Block level: ```bash lp=True, cwd='/tmp', asserts='barfoo', pre='touch barfoo|true', post='rm barfoo' ls | grep barfoo

- Statement level:

<!-- id: 769df295faa580e12128bda02816d4d6 -->

LP Source:

```bash

 ```bash lp cwd=/tmp asserts=foobar session=test
 [{'pre': 'touch foobar|true', 'cmd': 'ls foo*', 'asserts': 'foobar', 'post': 'rm foobar'},
 'ls foobar # lp: asserts="cannot"']
 ```

Result:

Cmd

$ ls foo*
$ ls foobar # lp: asserts="cannot"

Output

runner@fv-az135-986:/tmp$ ls foo*                     
foobar
runner@fv-az135-986:/tmp$ ls foobar # lp: asserts="cannot"                      
ls: cannot access 'foobar': No such file or directory                           
runner@fv-az135-986:/tmp$

Given at block level, the post command is only run once, even if there are more than one individual statements within the body of the block.

pre¤

pre=<some command>

Runs something, before the (output recorded) commands

Examples

Block level: ```bash lp=True, cwd='/tmp', asserts='barfoo', pre='touch barfoo|true' ls | grep bar

- Statement level:

<!-- id: 965b08f5197dc837bb67c52329d528b6 -->

LP Source:

```bash

 ```bash lp cwd=/tmp asserts=foobar session=test
 {'pre': 'touch foobar|true', 'cmd': 'ls foo*', 'asserts': 'foobar'}
 ```

Result:

Cmd

$ ls foo*

Output

runner@fv-az135-986:/tmp$ ls foo*                     
foobar

Given at block level, the pre command is only run once, even if there are more than one individual statements within the body of the block.

prompt¤

prompt=<prompt>

Sets the prompt string

Default is '$ '.

Example

LP Source:

 ```bash lp prompt="/foo/bar>" session=docutest
 echo -e '$ foo'
 ```

Result:

Cmd

/foo/bar> echo -e '$ foo'

Output

$ echo -e '$ foo'                                     
$ foo

In sessions we do this by exporting $PS1 to the given value, plus a space, at beginning of the session.

session¤

session=<tmux session name>

Runs the block within a tmux session

If the session already exists, it will be re-used.

Example

LP Source:

 ```bash lp session=docutest
 tmux list-sessions | grep docutest
 ```

Result:

Cmd

$ tmux list-sessions | grep docutest

Output

$ tmux list-sessions | grep docutest                  
docutest: 1 windows (created Mon Oct  4 21:03:20 2021)

Here is more about sessions.

silent¤

(boolean)

Run the command(s) normally but do not create any markdown

Examples

LP Source:

 ```bash lp
 rm /tmp/silent_test || true
 ```

Result:

Cmd

$ rm /tmp/silent_test || true

Output

$ rm /tmp/silent_test || true
rm: cannot remove '/tmp/silent_test': No such file or directory

LP Source:

 ```bash lp silent
 touch /tmp/silent_test
 ```

Result:

nothing is shown for block execution but the command was executed:

LP Source:

 ```bash lp
 ls -lta /tmp/silent_test
 rm /tmp/silent_test # lp: silent
 ```

Result:

Cmd

$ ls -lta /tmp/silent_test

Output

$ ls -lta /tmp/silent_test
-rw-r--r-- 1 runner docker 0 Oct  4 21:03 /tmp/silent_test

The last line shows silent on statement level.

src¤

src=<filename, relative to page or absolute>

References a source file

This header parameter standardizes the use of external sources, e.g. for diagrams (plantuml, drawio, mermaid, ...). Their mtime (last modification time) goes into the hash of the whole LP block, thus triggering re-evaluation (e.g. a diagram to svg conversion) when the source changed. Note that the lp block stays constant, i.e. we would otherwise not re-eval the block when eval policy is the usual on_change.

For plugin convenience this automatically also adds an abs_src parameter into the header arguments, with the page's absolute directory resolved.

timeout¤

timeout=<seconds> (session only cmd)

Time until timeout error is raised, waiting for results in sessions

Example

This would fail with timeout error:

 ```bash lp timeout=0.1 session=test
 sleep 0.2
 ```

with_paths¤

(boolean) (session only cmd)

Before a sequence of commands is run, we export $PATH and $PYTHONPATH of the calling process within tmux

A tmux session is started by issuing the tmux command - which starts the tmux server process, when there is non running. It might have a different process environment than the mkdocs process. With with_paths we export the two critical parameters before starting tmux.

Supported Parameters¤

addsrc / addsrc=&lt;fmt|title&gt;¤

asserts¤

body¤

cwd¤

eval¤

expect¤

fetch¤

fmt¤

hide_cmd¤

kill_session¤

mode¤

new_session¤

pdb¤

post¤

pre¤

prompt¤

session¤

silent¤

src¤

timeout¤

with_paths¤

addsrc / addsrc=`<fmt|title>`¤