Your First Angreal

This project is available under the example folder of the git repository.

This a very simple project for taking meeting minutes !

We have some basic requirements for this template :

  • on creation a folder with the meeting name will be created
  • on creation a file that introduces us to the reason the meetings exist as an initial README.
  • a task to take minutes using an editor

Template Layout

Based on the above planned requirements we’ll need files and folders created as follows :

meeting_notes
├── angreal.toml
└── {{ name }}
    ├── .angreal
    │   ├── init.py
    │   └── task_take_notes.py
    └── README.md

angreal.toml

The angreal.toml file tells angreal what variables it needs to template and provides default values for them. Our template will have the following variables:

  • name
  • cadence
  • standing_agenda
name="another_meeting"
cadence="weekly"
standing_agenda="Complaints"

README.md

The README.md is just meant to be a highlevel description of the meeting so you can remember why you’re there every week.

# {{ name }}


## Cadence

{{ cadence }}


## Standing Agenda

{{ standing_agenda }}

init.py

Optional: In this very trivial example, not much happens after the folder structure is created so the init isn’t required.

def init():
    print("Initializing {{ name }} !")
    return

task_take_notes.py

Angreal tasks must be a function in a python file that starts with task_ in the .angreal folder.

import angreal

import datetime
import os
import subprocess
import tempfile


@angreal.command(name='take-notes', about='Take notes for our meeting')
@angreal.argument(name='now',long='now', takes_value=False)
def angreal_cmd(now=False):
    """
    create a file for taking minutes
    """
    file_name = datetime.datetime.today().strftime('%Y-%m-%d-%H-%M')

    # We're going to assume that you're running on ubuntu
    # which has a binary called "editor" that will launch your
    # default terminal editor. If you need something else - set the environment
    # variable "EDITOR" to the appropriate command
    editor = os.environ.get('EDITOR','editor')

    # Create our default file template using the current time as a header
    (fd, path) = tempfile.mkstemp()
    with open(fd, 'w') as default:
        print('# {}'.format(file_name), file=default)

    # We want to start writing now if we're able
    if now and editor:
        subprocess.call('{} {}'.format(editor,path), shell=True)


    # Send the finalized contents of the temporary file to the actual file
    with open(file_name+'.md', 'a') as dst:
        with open(path,'r') as src:
            print(src.read(),file=dst)

    # Clean up behind our selves
    os.unlink(path)

A brief explanation of this code: - import angreal and other libraries - decorate a function with the command - we decorate the same function with an argument

The function itself:

  • determines the current date/time
  • tries to get an EDITOR variable from the environment, falling back to the editor command from Ubuntu
  • if you pass the --now argument, opens a temporary file using your editor
  • saves the notes taken to a file with the date and time the minutes were started.

Using our Angreal

  1. Initialize our template.
$ angreal init docs/content/tutorials/meeting_notes

cadence? ["weekly"]
>
name? ["another_meeting"]
> Hall of the Tower
standing_agenda? ["Complaints"]
> Discussing embroidery and fine turned calves

Initializing Hall of the Tower !

$ tree 'Hall of the Tower'
Hall of the Tower
└── README.md

$ cat Hall\ of\ the\ Tower/README.md                                                                                                            ─╯
# Hall of the Tower


## Cadence

Weekly


## Standing Agenda

Discussing embroidery and fine turned calves.
  1. What commands do i have access to ?
$ cd 'Hall of the Tower'
$ angreal

angreal 2.0.0-rc.1

USAGE:
    angreal <SUBCOMMAND>

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    help          Print this message or the help of the given subcommand(s)
    init          Initialize an Angreal template from source.
    take-notes    Take notes for our meeting
  1. How do i use take-notes ?
$ angreal take-notes --help

take-notes

    create a file for taking minutes


USAGE:
    take-notes [OPTIONS]

OPTIONS:
    -h, --help
            Print help information

        --now
            open editor immediately

Lets take some minutes, right now

$ export EDITOR='vim'
$ angreal take-minutes --now

This will open an editor (vim if you set the EDITOR variable) write a note.

$ ls                                                                                                                                            ─╯
2023-01-19-09-19.md  README.md