Package: rundoc
rundocA command-line utility that runs code blocks from documentation written in markdown.OverviewThis utility allows you to run your markdown files as if they were scripts. Every code snippet with code highlighting tag is run with interpreter defined by the tag.Why do this?We had a very long installation documentation for our project and needed a quick way of testing it. That's how rundoc is born. It is now a general purpose tool that can be used for multiple purposes like executing a tutorial documentation, using docs as a script, etc.Installationinstall from pypi (recommend)pip3 install rundocinstall from git (latest master)pip3 install -U git+https://github.com/eclecticiq/rundoc.gitUsageRundoc collects fenced code blocks from input markdown file and executes them in same order as they appear in the file. Interpreter is specified by the highlight tag of the code block.Example of fenced code block in markdown file:```bash
for x in `seq 0 10`; do
    echo $x
    sleep 1
done
```Interpreter will be automatically selected using the highlight tag of the code block (in above examplebash). Code is piped to the interpreter through stdin. If highlight tag is not specified, rundoc will ignore that code block.Rundoc can save json file after execution, which contains all code blocks and their outputs. You can also replay all the actions by running this output file.WARNING: Each code block is treated as separate step and is run in fresh interpreter session!Variables that you exported in the code block willnotbe passed to next code block. You can specify global variables inenvcode block (seeEnvironment variablesbelow).Run markdown fileExecute code blocks ininput.mdfile:rundocruninput.mdRundoc will execute all fenced code blocks that contain highlight tag.Get a promptYou will be prompted before executing each code block with ability to modify the input.When done reviewing/modifying the code block, pressReturnto execute it and move to the next one.Program will exit when last code block is finished executing or when you pressctrl+c.Get promptsSince version0.3.0, rundoc will just run everything by default, prompting you only for missing variables at the beginning. you can use single or multiple-aoptions to enable more prompts:-a- Ask (prompt) for all variables.-aa- Also ask to modify code block on failure and start over at that step.-aaa- Also prompt with each code block before executing it.rundocrun-aaainput.mdThe above will show each code block and allow you to modify it and press <RETURN> to run it.BreakpointsYou can force the prompt on specific steps using-bor--breakpointoption followed by a step number. You can use this option multiple times to add multiple breakpoints. When used, rundoc will stop at the selected steps and prompt user to modify code regardless of the--asksetting.PauseIf you need to add a delay between codeblocks, you can add-por--pauseoption to specify number of seconds for the puase. (This option does nothing in conjunction with-aaa):rundocrun-p2input.mdSome step fails first couple of times but it's normal? That may happen and you would just want to retry that step a couple of times. To do so use-ror--retryoption followed by max number of retries and rundoc will run the same step again until it succeeds or reaches max retries in which case it will exit:rundocrun-r10input.mdBut you don't want it to retry right away, correct? You can specify a delay between each try with-P(capital P) or--retry-pauseoption followed by number of seconds:rundocrun-r10-P2input.mdStart from specific stepYou can start at specified step using-sor--stepoption:rundocrun-s5input.mdThis is useful when your N-th code block fails and rundoc exits and you want to continue from that step.Save outputOutput can be saved as a json file containing these fields:env(dict): dictionary of set environment variables for the sessioncode_blocks(list): list of code blocks that contains the followingcode(str): original codeinterpreter(str): interpreter used for this code blocktags(str): tags as they appear in markdown fileruns(list): list of run attemptsoutput(str): merged stdout and stderr of the code block executionretcode(int): exit code of the code blocktime_start(float): timestamp when execution started (seconds from epoch)time_stop(float): timestamp when execution finished (seconds from epoch)user_code(str): code that user actually executed with promptTo save output use-oor--outputoption when running rundoc:rundocruninput.md-ooutput.jsonTagsBy default, rundoc executes all fenced code blocks that have highlithing tag set in markdown file. If you want to limit execution to subset of the code blocks, use tags. Tags can be specified with-tor--tagsoption followed by hash (#) separated list of tags:rundocrun-tbash#python3input.mdThis will execute only those code blocks that have at least one of the specified highlight tags: in this example onlybashandpythoncode blocks.If you want to further isolate code blocks of the same highlight tag, you can use rundoc tag syntax, e.g.:```bash#custom-branch#v2#test
echo "custom-tagged code block"
```In this syntax, multiple tags are applied to same code block and are separated with hash symbol#. In the example above there are 4 tags:bash,custom-branch,v2andtest. First tag always defines the interpreter. If any of it's tags is specified by-tor--tagsoption, it will be executed. Code blocks that do not contain at least one of the specified tags will be skipped.More tagsIn addition to-tor--tagsoption, you can also use the following 2 options to furthere fine-tune your code block filtering:-Tor--must-have-tags- same as--tagsbut it requires all listed tags to be present in the markdown code block or it will be skipped. The order of tags is not important.-N, or--must-not-have-tags- same as--tagsbut it requres thatnoneof the listed tags is present in the markdown code block. It is used to filter out unwanted ones.You can use any of the tags features individually or combine them.Environment variablesDefine required environment variables anywhere in the documentaion with a special code block tagged asenvorenvironmentat the beginning:```env#version5
var1=
var2=
var3=default_value_3
var4=default_value_4
```As in example above, define variables one on each line.When you run the docs with-aoption, you will be prompted for all of those.Empty values (e.g.var1andvar2in example) will try to collect actual values from your system environment, so ifvar1was exported before you ran the docs, it will collect it's value as the default value and will not prompt you for it if-aoption was not used.All variables will be passed to env for every code block that's being executed.If you use rundoc with tag option-t, environment blocks will be filtered in the same way as code blocks.Code blocks will only be selected if no tags are specified on executionorany of the selected code blocks contains at least one of the env's tags (in the above caseversion5).SecretsYou can define required credentials or other secrets anywhere in the documentaion as a special code block tagged assecretorsecretsat the beginning:```secrets#production
username=
password=
```Secrets behave just asenvblocks with one single difference: they are never saved in the output file and areexpected to be empty in markdown fileso that user must provide them during execution. If you want to use rundoc as part of automation and can't input secrets by hand, you can always export them beforehand and use-ioption (see next section).Action tagsAction tags are special tags that are used as a first tag instead of interpreter. Code blocks with these tags are not going to be executed, but will be used to perform specific actions, like creating a file.To get a list of available action tags and their usage in current version run:rundoc action-tags. New action tags will be included often in new versions of rundoc.Force variable collectionYou can force rundoc to check if any of the variables defined withenvtag is already exported in your current system environment and use it's value instead of the one defined in markdown file. To do this use-ior--inherit-envoption when running rundoc. The list of variables that is presented to you when you run rundoc and that will be used in the session will now contain values defined in the system environment.exportvar2=system_value_2exportvar3=system_value_3
rundocruninput.md-iSingle sessionBy default, all code blocks are run in separate interpreter sessions. If you define a function or set a variable in one code block, it will not be available in next one.To work around this use--single-sessionoption followed by the name of the interpreter. All code blocks will be merged into a single step.Note that only one interpreter type can be run per markdown file if you use single session option.rundoc run input.md --single-session bashReplayTo replay all code blocks found in output ofruncommand, just usereplaycommand like so:rundocreplayoutput.jsonThe above command will just turn last runs of each code block into a new code block and run them. It will ignore all run tries that did not succeed at first. Last run may have original command or user modified one and replay does not care about that, it just runs the last command it finds in each code block.You can still use-aaa,-p,-s,-o,-r, and-Poptions withreplaycommand:rundocreplay-s2-p1-r20-P5output.json-oreplay_output.jsonTips and tricksColor outputAre you using light terminal background and can't see sh*t? Use rundoc with--lightoption and save your eyesight!List tagsYou can list all unique tags that appear in the file and their counts by usinglist-tagscommand:rundoclist-tagsinput.mdList code blocksWouldn't it be great to be able to list all code blocks that are going to be executed before actually usingruncommand? You can! To print json file similar to output but without actually running anything you can uselist-blockscommand:rundoclist-blocks-tbash-Ttag1#tag2#tag3-Ntag4#tag5input.mdor add--prettyoption to have human readable output:rundoclist-blocks-tbash-Ttag1#tag2#tag3-Ntag4#tag5input.md--prettySimilar projectsList of similar projects that I found:codedownrunDOC(I was not aware of this one when I named my project, honest!)gfm-code-blocksIf you bump into more, let me know.