Tutorial: Assistants Utilizing PingPong

Regardless of which language you want to choose for implementing the PingPong script, you should read this section. It provides general information about specifying metadata, dependencies, arguments and file placement for the PingPong scripts.

DevAssistant distinguishes four different assistant roles - Creator, Tweak, Preparer, Extras. From the point of view of this tutorial, the roles only differ in file placement and where they’ll be presented to user on command line/in GUI. Therefore we choose to create a simple Creator. We’ll be implementing an assistant, that creates a simple reStructuredText document.

Note on terminology: The PingPong script is not the assistant. Even if you’re using the PingPong approach, the assistant is still a Yaml file (very simple in this case).

General Rules

Some things are common for all assistant types:

  • Each assistant is one Yaml file, that must contain exactly one mapping - the so-called assistant attributes:

    fullname: My Assistant
description: This will be part of help for this assistant
...

  • You have to place them in a proper place, see DevAssistant Load Paths and Assistants Loading Mechanism.

  • Files (e.g. templates, scripts, PingPong script files etc.) used by assistant should be placed in the same load dir, e.g. if your assistant is placed at ~/.devassistant/assistants, DevAssistant will look for files under ~/.devassistant/files.

  • As mentioned in DevAssistant Load Paths, there are three main load paths in standard DevAssistant installation, “system”, “local” and “user”. The “system” dir is used for assistants delivered by your distribution/packaging system and you shouldn’t touch or add files in this path. The “local” path can be used by system admin to add system-wide assistants while not touching “system” path. Lastly, “user” path can be used by user to install assistants just for himself.

  • When developing new assistants, that you e.g. put in a separate Git repo and want to work on it, commit, push, etc, it is best to utilize DEVASSISTANT_PATH bash environment variable, see DevAssistant Load Paths for more info.

Getting Set Up

To get started, we’ll create a file hierarchy for our new assistant, say in ~/programming. We’ll also modify DEVASSISTANT_PATH so that DevAssistant can see this assistant in directory outside of standard load paths. Luckily, there is assistant that does all this - dap:

da pkg install dap
da create dap -n ~/programming/rstcreate --crt
export DEVASSISTANT_PATH=~/programming/rstcreate/

Running da create dap scaffolds everything that’s needed to create a DAP package that can be distributed on DevAssistant Package Index, DAPI, see Packaging and Distributing Your Assistant for more information.

Since this assistant is a Creator, we need to put it somewhere under assistants/crt directory. The related files (if any), including the PingPong script have to go under files/crt/rstcreate (assuming, of course, we name the assistant rstcreate.yaml). More details on assistants file locations and subassistants can be found in the tutorial for the Yaml DSL.

Now go to one of the language-specific tutorials to see how to actually create a simple assistant and the PingPong script.