Differential D90

updating docs to explain task yaml format. Fixes T157
ClosedPublic
Actions

Authored by tflink on May 9 2014, 5:20 AM.

Tags

None

Subscribers

None

Details

Reviewers

kparal
roshi

Maniphest Tasks

T157: write taskyaml documentation

Commits

rLTRN8bfc6db62315: updating docs to explain task yaml format. Fixes T157

Summary

initial docs for task yaml format

Test Plan

just docs, no test plan needed. just review

Diff Detail

Lint

Lint Skipped

Unit

Unit Tests Skipped

Thanks, looking good. A few fixes needed.

docs/source/taskyaml.rst
109–114	Two problems: When I read this in html, I wasn't able to understand the "a:" word. It's clear here in the source, but the italicized colon is very unclear in html (and if you intended to make it a monospaced instead of italicized, it's not better) . I think it's best to write "colon" instead of ":". Even though I know what it is about, I had a hard time to understand it. Can we make it simpler and include an example? For example: Important: If your variable is directly following a colon, surround it in quotes so that the yaml parser interprets it as a string. Right: `arg1: "{{ var1 }}"` . Wrong: `arg1: {{ var1 }}`.
142–149	I guess the export value should be called `firststep_output`, because it is then consumed by `second step`.
151–153	The names of directives and exports don't match the example.

updating taskyaml docs to address concerns from review

Looks good.

docs/source/taskyaml.rst
159–161	When reading it again, maybe the second sentence is not necessary at all. Everything important has been described in the first one. But that's just a side note.

Closed by commit rLTRN8bfc6db62315 (authored by @tflink).

Revision Contents

			Path
M			docs/source/index.rst (1 line)
A	M		docs/source/taskyaml.rst (169 lines)

Diff 259

docs/source/index.rst

Show All 30 Lines
31	========	31		========
32		32
33	.. toctree::	33		.. toctree::
34	:maxdepth: 1	34		:maxdepth: 1
35		35
36	devguide	36		devguide
37	writing_tasks	37		writing_tasks
38	library	38		library
		39		taskyaml
39		40
40		41
41	Indices and tables	42		Indices and tables
42	==================	43		==================
43		44
44	* :ref:`genindex`	45		* :ref:`genindex`
45	* :ref:`modindex`	46		* :ref:`modindex`
46	* :ref:`search`	47		* :ref:`search`
47		48

docs/source/taskyaml.rst

This file was added.

		1		==========================
		2		Taskotron Task YAML Format
		3		==========================
		4
		5		One of the core bits of Taskotron is the yaml file used to describe tasks to be
		6		run. As Taskotron is still a very young project, some components of the task yaml
		7		files are not yet used by the task runner but are useful to human readers of
		8		the task. Those sections will be noted and those notes updated as things change.
		9
		10		The documentation here is a description of how things are implemented but are
		11		a little light on the practical creation of tasks. link to task creation howto
		12		and some existing tasks are also good references:
		13
		14		* `rpmlint <https://bitbucket.org/fedoraqa/task-rpmlint>`_
		15		* `examplebodhi <https://bitbucket.org/fedoraqa/task-examplebodhi>`_
		16
		17		Task Description
		18		================
		19
		20		Metadata
		21		--------
		22
		23		Some metadata is required to be in the task yaml file:
		24
		25		* task name
		26		* description
		27		* maintainer
		28
		29		.. code-block:: yaml
		30
		31		---
		32		name: rpmlint
		33		desc: download specified rpms and run rpmlint on them
		34		maintainer: tflink
		35
		36		.. note::
		37
		38		Please use a FAS account name for the maintainer
		39
		40
		41		Input
		42		-----
		43
		44		Most tasks require some form of input. The required input must be declared in
		45		order to verify that the task can be run
		46
		47		.. code-block:: yaml
		48
		49		input:
		50		args: arch, envr
		51
		52		Valid args include:
		53
		54		* arch
		55		* envr
		56		* bodhi_id
		57		* koji_tag
		58
		59		Dependencies
		60		------------
		61
		62		A task may also require the presence of other code to support execution. Those
		63		dependencies are specified as part of the environment description.
		64
		65		.. code-block:: yaml
		66
		67		environment:
		68		rpm:
		69		- rpmlint
		70		- libtaskotron
		71
		72		.. note::
		73
		74		At this time, the list of rpm dependencies is not checked during execution
		75		but this will change in future versions. For now, this section is ignored and
		76		is mostly for human reference.
		77
		78		.. note::
		79
		80		Future versions will also support specifying dependencies in other formats
		81		than RPM.
		82
		83
		84		Task Execution
		85		==============
		86
		87		Every task is defined in the `task` block of the task yaml file. The task
		88		consists of one or more steps which consist of a name, directive and optional
		89		export of data.
		90
		91		.. code-block:: yaml
		92
		93		task:
		94		- name: using directivename for something
		95		directivename:
		96		arg1: value1
		97		arg2: "{{ some_variable }}"
		98		export: somestep_output
		99
		100
		101		Variable Storage and Syntax
		102		---------------------------
		103
		104		The task yaml file uses standard `jinja2 <http://jinja.pocoo.org/>`_ syntax for
		105		variables. Variables can be created during task execution or provided by default
		106		by the task runner.
		107
		108		.. note::
		109
		110		An unfortunate side-effect of using jinja2 syntax with yaml files is that the
		111		yaml parser tends to view variables as invalid dictionaries. If the variable
		112		is directly following a colon, make sure to surround it in quotes so that the
		113		yaml parser interprets the variable as a string.
		114
			kparalUnsubmitted Not Done Two problems: When I read this in html, I wasn't able to understand the "a:" word. It's clear here in the source, but the italicized colon is very unclear in html (and if you intended to make it a monospaced instead of italicized, it's not better) . I think it's best to write "colon" instead of ":". Even though I know what it is about, I had a hard time to understand it. Can we make it simpler and include an example? For example: Important: If your variable is directly following a colon, surround it in quotes so that the yaml parser interprets it as a string. Right: `arg1: "{{ var1 }}"` . Wrong: `arg1: {{ var1 }}`.
		115		.. code-block:: yaml
		116
		117		# this will not parse well
		118		arg1: {{ some_variable }}
		119
		120		# this will parse properly
		121		arg1: "{{ some_variable }}"
		122
		123		Provided Variables
		124		------------------
		125
		126		The task runner provides the following variables without a need for them to be
		127		explicitly specified:
		128
		129		* workdir
		130		* jobid
		131
		132		.. note::
		133
		134		The `jobid` is used primarially for reporting to render proper log and job
		135		urls. It can be specified on the command line but isn't required for local
		136		execution. If a `jobid` is not explicitly provided at execution time, a
		137		sane default value will be provided by the runner.
		138
		139		Created Variables
		140		-----------------
		141
		142		There are many situations in which the output from one step is used as input
		143		for another step which is executed later. In order for a step's output to be
		144		used later, it must first be exported.
		145
		146		.. code-block:: yaml
		147
		148		task:
		149		- name: first step
			kparalUnsubmitted Not Done I guess the export value should be called `firststep_output`, because it is then consumed by `second step`.
		150		directive_one:
		151		arg1: value1
		152		export: firststep_output
		153
			kparalUnsubmitted Not Done The names of directives and exports don't match the example.
		154		- name: second step
		155		directive_two:
		156		arg1: "{{ firststep_output }}"
		157
		158		In this example, the output from `first step` is stored as `firststep_output`
		159		and later used by `second step`. Once the `first step` is executed, its
		160		output is stored as a variable using the name following `export:`.
		161
			kparalUnsubmitted Not Done When reading it again, maybe the second sentence is not necessary at all. Everything important has been described in the first one. But that's just a side note.
		162
		163		Directives
		164		==========
		165
		166		The directives which are used in task steps are defined in libtaskotron. These
		167		directives are grouped into three types: preparation, execution and reporting.
		168
		169		Needs some sort of link or list of directives and their documentation