Via The Repo¶

To install Færeld from the repo, you can clone it and set up a clean environment with virtualenv:

git clone git@github.com:Autophagy/faereld.git
cd faereld
virtualenv .venv -p python3.6
source .venv/bin/activate

Then, install the package:

pip install --user -e .

You can now run Færeld via faereld insert.

Summary Mode¶

Summary mode can be used via:

$ faereld summary

Summary mode will print several summaries of the available Færeld data including:

• Summary of total days, entries and hours logged.
• Bar graph of total time logged per area.
• Box plot diagram of entry time distribution per area (except IRL).
• The last 10 entries logged.

Projects Mode¶

Projects mode can be used via:

$ faereld projects

Projects mode will print a summary of the total time logged per project.

Productivity Mode¶

Productivity mode can be used via:

$ faereld productivity

Productivity mode will print a summary of the total time logged per day of the week and total time logged per hour of the day.

Insert Mode¶

Insert mode can be used via:

$ faereld insert

Færeld will first ask you to choose the area that the current task belongs to. For a list of areas and their explainations, see the Areas documentation.

[ Areas :: RES // DES // DEV // DOC // TST // IRL // RDG // LNG ]
Area :: DEV

If the chosen area is a project specific one (RES, DES, DEV, DOC or TST) then you will be asked to enter the project that this task belongs to. These projects can be defined in the Configuration.

[ Objects :: faereld // insegel // datarum // aerende // antimber // hraew ]
Object :: faereld

If the area is a non-project specific one, then you will be prompted to just fill out the name of whatever the task is. If you already have tasks logged for a non-project area, Færeld will provide a list of the last 5 (by default) unique tasks added to it, which can be selected via entering the key of that entry. The number of tasks returned can be modified in the Configuration.

Last 5 RDG Objects ::

[0] Benjamin H. Bratton's The Stack: On Software and Sovereignty
[1] Reza Negarestani's Cyclonopedia: Complicity with Anonymous Materials
[2] Manuel DeLanda's Assemblage Theory
[3] Herman Meville's Moby Dick
[4] Jorge Luis Borges' Fictions

Object :: [0]

You will then be asked to enter the start and end datetime of the task. This task must be in form Day Short-Month Year // 24H.M. For example, a task beginning on the 3rd of December 2017 at 10pm should be entered as:

From :: 03 Dec 2017 // 22.00

Similar rules apply if using Wending mode dates, which are disabled by default. To quickly input the current date and time, regardless of which date mode you are using, enter now:

From :: now

Data Options¶

Summary Options¶

Project Areas¶

Project area definitions should be of the form:

code:
  name: Area Name
  rendering_string: On {date} I worked on {object} ({area_name}) for {duration}

For example, the default Development area is defined as follows:

DEV:
  name: Development
  rendering_string: On {date} I worked on {object} ({area_name}) for {duration}

The rendering_string is used within Færeld to render an entry. The above defition would render a 30 minute development task on 2nd Jan 2017 for Project A as:

On 02 Jan 2017 I worked on Project A (Development) for 30m

To render the string diferently, change this configuration option. For example, to generate the rendered string:

[02 Jan 2018] -- Development -> Project A (30m)

You would configure the rendering_string as:

rendering_string: [{date}] -- {area_name} -> {object} ({duration})

The valid substitution options for a project area’s rendering string are:

• {area} :: The area code of the entry (e.g. DEV)
• {area_name} :: The name of the area of the entry (e.g. Development)
• {object} :: The name of the object of the entry (e.g. Project A)
• {date} :: The date of the start date of the entry (e.g. 02 Jan 2017)
• {duration} :: The duration of the entry (e.g. 30m)
• {start} :: The start time of the entry (e.g. 18:00)
• {end} :: The end time of the entry (e.g. 23:42)

Projects¶

Projects are defined within the config.yml, but there are no defaults. A project must be defined in the following way:

projects:
  hraew:
    desc: A project information & documentation engine.
    link: https://github.com/Autophagy/hraew
    name: Hrǽw
  scieldas:
    desc: A service to provide metadata badges for Open Source projects.
    link: https://github.com/Autophagy/scieldas
    name: Scieldas

General Areas¶

General rea definitions should be of the form:

code:
  name: Area Name
  rendering_string: On {date} I worked on {object} for {duration}

For example, the default Reading area is defined as follows:

RDG:
  name: Reading
  rendering_string: On {date} I read {object} for {duration}
  use_last_objects: true

The rendering_string is used within Færeld to render an entry. The above defition would render a 30 minute reading task on 2nd Jan 2017 for Book A as:

On 02 Jan 2017 I read Book A for 30m

To render the string diferently, change this configuration option. For example, to generate the rendered string:

[02 Jan 2018] -- Reading -> Book A (30m)

You would configure the rendering_string as:

rendering_string: [{date}] -- {area_name} -> {object} ({duration})

The valid substitution options for a project area’s rendering string are:

• {area} :: The area code of the entry (e.g. RDG)
• {area_name} :: The name of the area of the entry (e.g. Reading)
• {object} :: The name of the object of the entry (e.g. Book A)
• {date} :: The date of the start date of the entry (e.g. 02 Jan 2017)
• {duration} :: The duration of the entry (e.g. 30m)
• {start} :: The start time of the entry (e.g. 18:00)
• {end} :: The end time of the entry (e.g. 23:42)

The use_last_objects option defines that, upon insertion of that area, whether the last x objects (x being the defined value in data_options: num_last_projects to be inserted into that area are printed. These can then be used as short hand when inserting an entry. For example, on inserting a Reading task:

[ Areas :: RES // DES // DEV // DOC // TST // IRL // RDG // LNG // TSK ]
Area :: RDG

Last 5 RDG Objects ::
[0] Italo Calvino's Our Ancestors
[1] Iain M. Banks' Look to Windward
[2] David Peak's The Spectacle of the Void
[3] Benjamin H. Bratton's The Stack: On Software and Sovereignty
[4] Herman Meville's Moby Dick
Object :: [0]

In this example, selecting [0] as the object would then insert Italo Calvino's Our Ancestors into Færeld.