Differential D163

Docs: Parameters table enhancements
ClosedPublic
Actions

Authored by jskladan on Jun 26 2014, 10:46 AM.

Details

Reviewers
kparal
roshi
tflink
Maniphest Tasks
T259: directive docs: support reST in option description and default value
T260: directive docs: improve option table appearance
Commits
rLTRN63c2ebfc3c70: Docs: RST in parameters table
Summary

Table contents can be styled, and the table itself looks much better
now. See koji_utils_directive for an example.

Test Plan

none

Diff Detail

Repository
rLTRN libtaskotron
Branch
feature/rst_in_params
Lint
No Linters Available
Unit
No Unit Test Coverage
jskladan retitled this revision from to Docs: Parameters table enhancements.Jun 26 2014, 10:46 AM
jskladan updated this object.
jskladan edited the test plan for this revision. (Show Details)
jskladan added reviewers: kparal, tflink, roshi.
jskladan updated this revision to Diff 475.Jun 26 2014, 12:09 PM
  • Docs: Sane params table
  • CSS fix
  • fix some newline issues
  • adjust param descriptions in directives to use reST
roshi accepted this revision.Jun 26 2014, 10:31 PM

Looks good to me.

This revision is now accepted and ready to land.Jun 26 2014, 10:31 PM
kparal accepted this revision.Jun 27 2014, 8:54 AM

Let's push it.

jskladan closed this revision.Jun 27 2014, 9:02 AM

Revision Contents

Diff 475

View Options

docs/directives_template/rst.j2

Show All 23 Lines
24@{ description }@ 24​@{ description }@
25 25​
26{% if parameters -%} 26​{% if parameters -%}
27Parameters 27​Parameters
28---------- 28​----------
29 29​
30.. raw:: html 30​.. raw:: html
31 31​
32 <table border=1 cellpadding=4> 32​ <table class="rawhtml" border=1 cellpadding=4>
33 <tr> 33​ <tr>
34 <th class="head">parameter</th> 34​ <th class="head">parameter</th>
35 <th class="head">required</th> 35​ <th class="head">required</th>
36 <th class="head">description</th> 36​ <th class="head">description</th>
37 <th class="head">type</th> 37​ <th class="head">type</th>
38 <th class="head">default</th> 38​ <th class="head">default</th>
39 <th class="head">choices</th> 39​ <th class="head">choices</th>
40 </tr> 40​ </tr>
41 {% for k in option_keys %} 41​ {% for k in option_keys %}
42 {% set v = parameters[k] %} 42​ {% set v = parameters[k] %}
43 <tr> 43​ <tr>
44 <td>@{ k | html_ify }@</td> 44​ <td class="bold">@{ k | html_ify | indent }@</td>
45 <td>{% if v.get('required', False) %}yes{% else %}no{% endif %}</td> 45​ <td>{% if v.get('required', False) %}yes{% else %}no{% endif %}</td>
46 <td>@{ v.description | html_ify | nl2br | indent }@{% if v['version_added'] %} (added in Taskotron @{v['version_added']}@){% endif %}</td> 46​ <td>@{ v.description | html_ify | indent }@{% if v['version_added'] %} (added in Taskotron @{v['version_added']}@){% endif %}</td>
47 <td>@{ v.type | html_ify }@</td> 47​ <td>@{ v.type | html_ify | indent }@</td>
48 <td>@{ v['default'] | html_ify }@</td> 48​ <td>@{ v['default'] | html_ify | indent }@</td>
49 <td><ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice | html_ify }@</li>{% endfor -%}</ul></td> 49​ <td><ul>{% for choice in v.get('choices',[]) -%}<li>@{ choice | html_ify | indent }@</li>{% endfor -%}</ul></td>
50 </tr> 50​ </tr>
51 {% endfor %} 51​ {% endfor %}
52 </table> 52​ </table>
53{% endif %} 53​{% endif %}
54 54​
55{% if returns -%} 55​{% if returns -%}
56Return Values 56​Return Values
57------------- 57​-------------
Show All 20 Lines
View Options

docs/generate_directive_docs.py

Show All 24 Lines
25import re 25​import re
26import optparse 26​import optparse
27import datetime 27​import datetime
28import cgi 28​import cgi
29import traceback 29​import traceback
30 30​
31from jinja2 import Environment, FileSystemLoader 31​from jinja2 import Environment, FileSystemLoader
32 32​
33​from docutils.core import publish_parts
34​
33# constants and paths 35​# constants and paths
34 36​
35# if a module is added in a version of Taskotron older than this, don't print 37​# if a module is added in a version of Taskotron older than this, don't print
36# the version added information in the module documentation because everyone 38​# the version added information in the module documentation because everyone
37# is assumed to be running something newer than this already. 39​# is assumed to be running something newer than this already.
38TO_OLD_TO_BE_NOTABLE = 0.0 40​TO_OLD_TO_BE_NOTABLE = 0.0
39 41​
40# Get parent directory of the directory this script lives in 42​# Get parent directory of the directory this script lives in
Show All 23 Lines60def rst_ify(text):
64 t = _MODULE.sub(r'``' + r"\1" + r"``", t) 66​ t = _MODULE.sub(r'``' + r"\1" + r"``", t)
65 t = _URL.sub(r"\1", t) 67​ t = _URL.sub(r"\1", t)
66 t = _CONST.sub(r'``' + r"\1" + r"``", t) 68​ t = _CONST.sub(r'``' + r"\1" + r"``", t)
67 69​
68 return t 70​ return t
69 71​
70 72​
71def html_ify(text): 73​def html_ify(text):
72 ''' convert symbols like I(this is in italics) to valid HTML ''' 74​ ''' convert rst to html '''
73 ​
74 t = cgi.escape(str(text)) ​
75 t = _ITALIC.sub("<em>" + r"\1" + "</em>", t) ​
76 t = _BOLD.sub("<b>" + r"\1" + "</b>", t) ​
77 t = _MODULE.sub("<span class='module'>" + r"\1" + "</span>", t) ​
78 t = _URL.sub("<a href='" + r"\1" + "'>" + r"\1" + "</a>", t) ​
79 t = _CONST.sub("<code>" + r"\1" + "</code>", t) ​
80 75​
81 return t 76​ out = publish_parts(str(text), writer_name="html")['body']
77​ out = out.strip()
78​ return out
82 79​
83 80​
84def nl2br(value): 81​def nl2br(value):
82​ ''' convert line feeds to <br/> '''
85 83​
86 return value.replace('\n\n', '<br/>\n') 84​ return value.replace('\n', '<br/>\n')
87 85​
88 86​
89def rst_fmt(text, fmt): 87​def rst_fmt(text, fmt):
90 ''' helper for Jinja2 to do format strings ''' 88​ ''' helper for Jinja2 to do format strings '''
91 89​
92 return fmt % (text) 90​ return fmt % (text)
93 91​
94 92​
▲ Show 20 Lines • Show All 366 Lines • Show Last 20 Lines
View Options

docs/source/_static/sane_directives_params_table.css

  • This file was added.
1​table.rawhtml {
2​ border-collapse: collapse;
3​}
4​
5​table.rawhtml * tr {
6​ border: 1px solid black;
7​}
8​table.rawhtml * td, th {
9​ border: 1px dotted grey;
10​ padding: 5px;
11​}
12​
13​table.rawhtml * td {vertical-align: top;}
14​
15​table.rawhtml * th.head {
16​ text-transform: capitalize;
17​ font-style: italic;
18​ font-weight: normal;
19​}
20​
21​table.rawhtml * td.bold {font-weight: bold}
22​
23​table.rawhtml * ul {
24​ padding: 0px;
25​ padding-left: 1em;
26​ margin: 0px;
27​}
28​
29​table.rawhtml * p {margin: 0; padding: 0}
View Options

docs/source/_templates/layout.html

  • This file was added.
1​{# layout.html #}
2​{# Import the theme's layout. #}
3​{% extends "!layout.html" %}
4​
5​{% set css_files = css_files + ['_static/sane_directives_params_table.css'] %}
View Options

libtaskotron/directives/__init__.py

Show All 18 Lines
19:meth:`~BaseDirective.process`` method. 19​:meth:`~BaseDirective.process`` method.
20 20​
21The documentation of the directives is done through two global variables - 21​The documentation of the directives is done through two global variables -
22``DOCUMENTATION`` and ``EXAMPLES``. In this file, you'll find a template for 22​``DOCUMENTATION`` and ``EXAMPLES``. In this file, you'll find a template for
23both these attributes.''' 23​both these attributes.'''
24 24​
25DOCUMENTATION = """ 25​DOCUMENTATION = """
26# This is structured as a YAML document. If a key doesn't apply to your 26​# This is structured as a YAML document. If a key doesn't apply to your
27# directive, simply remove it. You can use reST markup in all string fields 27​# directive, simply remove it. You can use reST markup in all string fields.
28# unless noted otherwise. If you need to include `:` or newlines in a string, 28​# If you need to include `:` or newlines in a string, start with with a `|`
29# start with with a `|` symbol and a newline, as shown below. 29​# symbol and a newline, as shown below.
30module: directive_name (same as the file name) 30​module: directive_name (same as the file name)
31short_description: one sentence describing the purpose of the directive 31​short_description: one sentence describing the purpose of the directive
32description: | 32​description: |
33 Full description of the directive. You can use inline markup in reST 33​ Full description of the directive. You can use inline markup in reST
34 format, like **bold** and `hyperlinks <http://example.org>`_. New paragraphs 34​ format, like **bold** and `hyperlinks <http://example.org>`_. New paragraphs
35 are separated by a blank line. 35​ are separated by a blank line.
36 36​
37 reST block markup is supported as well, simply ensure that your block is 37​ reST block markup is supported as well, simply ensure that your block is
38 indented correctly. Code markup example:: 38​ indented correctly. Code markup example::
39 39​
40 This is a preformatted 40​ This is a preformatted
41 code block 41​ code block
42 42​
43 Add notes like this: 43​ Add notes like this:
44 44​
45 .. note:: This sentence will get highlighted and framed in a block. 45​ .. note:: This sentence will get highlighted and framed in a block.
46parameters: 46​parameters:
47 # One or more options using the following format. You can't use any reST 47​ # One or more options using the following format.
48 # markup anywhere in this section, only plain text. ​
49 parameter_name: 48​ parameter_name:
50 required: true 49​ required: true
51 description: | 50​ description: |
52 Description of the option. 51​ Description of the option, again with some ``values`` formatting.
53 52​
54 Blank lines force a line break. 53​ Blank lines force a line break.
55 type: parameter type, e.g. `str` or `list of str` 54​ type: parameter type, e.g. `str` or `list of str`
56 default: a default value, if applicable; otherwise remove the line 55​ default: a default value, if applicable; otherwise remove the line
57 choices: [choices, separated, by, commas, if, applicable] 56​ choices: [choices, separated, by, commas, if, applicable]
58returns: | 57​returns: |
59 Describe the return value of this directive. Example: 58​ Describe the return value of this directive. Example:
60 59​
Show All 31 Lines
View Options

libtaskotron/directives/bodhi_comment_directive.py

Show All 21 Lines21 .. note:: You have to have ``fas_username`` and ``fas_password`` configured
22 in your config file, otherwise the comments won't be posted. 22​ in your config file, otherwise the comments won't be posted.
23parameters: 23​parameters:
24 results: 24​ results:
25 required: true 25​ required: true
26 description: single or multiple check results in TAP13 format 26​ description: single or multiple check results in TAP13 format
27 type: str 27​ type: str
28 doreport: 28​ doreport:
29 required: true 29​ required: true
30 description: Select `all` to always post the check result, regardless of 30​ description: |
31 previoust Taskotron comments for the same update. Select `onchange` to 31​ select ``all`` to always post the check result, regardless of
32 only post comments if the check result status changed (e.g. from `FAILED` 32​ previoust Taskotron comments for the same update. Select ``onchange`` to
33 to `PASSED`), or if the `FAILED` status repeats itself *and* long enough 33​ only post comments if the check result status changed (e.g. from ``FAILED``
34 time has passed between these two failures (configurable as 34​ to ``PASSED``), or if the ``FAILED`` status repeats itself **and** long
35 `bodhi_posting_comments_span` in the config file). For production purposes 35​ enough time has passed between these two failures (configurable as
36 you usually want to use `onchange`, for development purposes you might 36​ ``bodhi_posting_comments_span`` in the config file).
37 want to use `all`. 37​
38​ For production purposes you usually want to use ``onchange``, for
39​ development purposes you might want to use ``all``.
38 type: str 40​ type: str
39 choice: [all, onchange] 41​ choice: [all, onchange]
40returns: | 42​returns: |
41 A list of bool values. The number and order of the bool values matches the 43​ A list of bool values. The number and order of the bool values matches the
42 number and order of Bodhi update check results in ``results``. The bool value 44​ number and order of Bodhi update check results in ``results``. The bool value
43 is ``True`` if comment was posted successfully or comment wasn't meant to be 45​ is ``True`` if comment was posted successfully or comment wasn't meant to be
44 posted (either posting is turned off or comment was already posted), ``False`` 46​ posted (either posting is turned off or comment was already posted), ``False``
45 if some problem was encountered. 47​ if some problem was encountered.
▲ Show 20 Lines • Show All 435 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/bodhi_directive.py

Show All 11 Lines10description: |
12 At the moment, the only action supported is downloading updates (i.e. all RPMs 12​ At the moment, the only action supported is downloading updates (i.e. all RPMs
13 from all builds related to a specific update). 13​ from all builds related to a specific update).
14 14​
15 .. _Bodhi: https://admin.fedoraproject.org/updates/ 15​ .. _Bodhi: https://admin.fedoraproject.org/updates/
16parameters: 16​parameters:
17 action: 17​ action:
18 required: true 18​ required: true
19 description: specify action type. The only action available at the moment 19​ description: specify action type. The only action available at the moment
20 is `download`. 20​ is ``download``.
21 type: str 21​ type: str
22 bodhi_id: 22​ bodhi_id:
23 required: true 23​ required: true
24 description: Bodhi update ID to download. This is usually in the form of 24​ description: Bodhi update ID to download. This is usually in the form of
25 `FEDORA-2014-7485` or `pykickstart-1.99.42-1.fc20,anaconda-20.23-1.fc20`. 25​ ``FEDORA-2014-7485`` or ``pykickstart-1.99.42-1.fc20,anaconda-20.23-1.fc20``.
26 type: str 26​ type: str
27 arch: 27​ arch:
28 required: true 28​ required: true
29 description: | 29​ description: |
30 a list of architectures for which to download RPMs. In addition to 30​ a list of architectures for which to download RPMs. In addition to
31 architectures supported by Taskotron by default, `src` is supported as 31​ architectures supported by Taskotron by default, ``src`` is supported as
32 well. 32​ well.
33 33​
34 Note: `noarch` RPMs are always automatically downloaded even when not 34​ Note: ``noarch`` RPMs are always automatically downloaded even when not
35 requested, unless `src` is the only architecture requested. 35​ requested, unless ``src`` is the only architecture requested.
36 type: list of str 36​ type: list of str
37returns: | 37​returns: |
38 A dictionary containing following items: 38​ A dictionary containing following items:
39 39​
40 * `downloaded_rpms`: (list of str) a list of local filenames of the downloaded 40​ * ``downloaded_rpms``: (list of str) a list of local filenames of the
41 RPMs 41​ downloaded RPMs
42raises: | 42​raises: |
43 * :class:`.TaskotronDirectiveError`: if no update with ``bodhi_id`` has been 43​ * :class:`.TaskotronDirectiveError`: if no update with ``bodhi_id`` has been
44 found 44​ found
45 * :class:`.TaskotronRemoteError`: if downloading failed 45​ * :class:`.TaskotronRemoteError`: if downloading failed
46version_added: 0.4 46​version_added: 0.4
47""" 47​"""
48 48​
49EXAMPLES = """ 49​EXAMPLES = """
▲ Show 20 Lines • Show All 91 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/dummy_directive.py

Show All 9 Lines
10description: | 10​description: |
11 This is just what it sounds like - a directive that doesn't do anything other 11​ This is just what it sounds like - a directive that doesn't do anything other
12 than (optionally) return a message or raise an error. It is primarially meant 12​ than (optionally) return a message or raise an error. It is primarially meant
13 for testing the runner or as a placeholder while writing new tasks. Or you can 13​ for testing the runner or as a placeholder while writing new tasks. Or you can
14 play with it to learn the directive basics. 14​ play with it to learn the directive basics.
15parameters: 15​parameters:
16 result: 16​ result:
17 required: true 17​ required: true
18 description: arbitrary string. If it equals "FAIL" (case ignored), then the 18​ description: arbitrary string. If it equals ``FAIL`` (case ignored), then
19 directive raises an error. 19​ the directive raises an error.
20 type: str 20​ type: str
21 msg: 21​ msg:
22 required: false 22​ required: false
23 description: arbitrary string. If it is present, it is returned. 23​ description: arbitrary string. If it is present, it is returned.
24 type: anything 24​ type: anything
25returns: | 25​returns: |
26 Either ``msg``, if it was provided, or ``None``. 26​ Either ``msg``, if it was provided, or ``None``.
27raises: | 27​raises: |
Show All 36 Lines
View Options

libtaskotron/directives/koji_directive.py

Show All 12 Lines10description: |
13 a specific build, or you can download all RPMs from all builds belonging 13​ a specific build, or you can download all RPMs from all builds belonging
14 to a specific Koji tag. 14​ to a specific Koji tag.
15parameters: 15​parameters:
16 arch: 16​ arch:
17 required: true 17​ required: true
18 description: | 18​ description: |
19 a list of architectures for which to download RPMs for the requested 19​ a list of architectures for which to download RPMs for the requested
20 build/tag. In addition to architectures supported by Taskotron by default, 20​ build/tag. In addition to architectures supported by Taskotron by default,
21 `src` is supported as well. 21​ ``src`` is supported as well.
22 22​
23 Note: `noarch` RPMs are always automatically downloaded even when not 23​ Note: ``noarch`` RPMs are always automatically downloaded even when not
24 requested, unless `src` is the only architecture requested. 24​ requested, unless ``src`` is the only architecture requested.
25 type: list of str 25​ type: list of str
26 choices: [standard Taskotron architectures, src] 26​ choices: [standard Taskotron architectures, src]
27 command: 27​ command:
28 required: true 28​ required: true
29 description: choose whether to download a single build or all builds 29​ description: choose whether to download a single build or all builds
30 belonging to a Koji tag 30​ belonging to a Koji tag
31 type: str 31​ type: str
32 choices: [tag, build] 32​ choices: [tag, build]
33 koji_build: 33​ koji_build:
34 required: true 34​ required: true
35 description: | 35​ description: |
36 N(E)VR of a Koji build to download. Only required when 36​ N(E)VR of a Koji build to download. Only required when
37 `command="download"`. Example: `xchat-2.8.8-21.fc20` 37​ ``command="download"``. Example: ``xchat-2.8.8-21.fc20``
38 type: str 38​ type: str
39 koji_tag: 39​ koji_tag:
40 required: true 40​ required: true
41 description: | 41​ description: |
42 name of a Koji tag to download all builds from. Only required when 42​ name of a Koji tag to download all builds from. Only required when
43 `command="download_tag"`. Example: `f20-updates-pending` 43​ ``command="download_tag"``. Example: ``f20-updates-pending``
44 type: str 44​ type: str
45 target_dir: 45​ target_dir:
46 required: false 46​ required: false
47 description: directory into which to download builds 47​ description: directory into which to download builds
48 type: str 48​ type: str
49 default: ${workdir} 49​ default: ${workdir}
50returns: | 50​returns: |
51 A dictionary containing following items: 51​ A dictionary containing following items:
▲ Show 20 Lines • Show All 102 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/python_directive.py

Show All 14 Lines14parameters:
15 file: 15​ file:
16 required: true 16​ required: true
17 description: absolute or relative path to the python file to be executed 17​ description: absolute or relative path to the python file to be executed
18 (the task directory is considered the current working directory) 18​ (the task directory is considered the current working directory)
19 type: str 19​ type: str
20 callable: 20​ callable:
21 required: true 21​ required: true
22 description: name of the object to call. This can be a function reference, 22​ description: name of the object to call. This can be a function reference,
23 a callable instance reference, or an `instance.method` reference. See 23​ a callable instance reference, or an ``instance.method`` reference. See
24 examples. 24​ examples.
25 type: str 25​ type: str
26 <kwarg>: 26​ <kwarg>:
27 required: false 27​ required: false
28 description: arbitrarily named parameter with a value. All these `key=value` 28​ description: arbitrarily named parameter with a value. All these ``key=value``
29 pairs will be passed to the python script as `callable` parameters. 29​ pairs will be passed to the python script as ``callable`` parameters.
30 type: anything 30​ type: anything
31returns: | 31​returns: |
32 The output of the python script, which must be either ``None`` or a 32​ The output of the python script, which must be either ``None`` or a
33 ``basestring``. 33​ ``basestring``.
34 34​
35 If this python script is supposed to be the main check of the task, it is 35​ If this python script is supposed to be the main check of the task, it is
36 supposed to provide output in a `TAP13 format`_. This format is then used in 36​ supposed to provide output in a `TAP13 format`_. This format is then used in
37 the :ref:`resultsdb directive <resultsdb_directive>`. The easiest way to 37​ the :ref:`resultsdb directive <resultsdb_directive>`. The easiest way to
▲ Show 20 Lines • Show All 174 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/yumrepoinfo_directive.py

Show All 9 Lines
10description: | 10​description: |
11 Translate a Koji tag into a set of YUM repositories. This is useful when you 11​ Translate a Koji tag into a set of YUM repositories. This is useful when you
12 want to work with YUM metadata for a specific Fedora repository, but you only 12​ want to work with YUM metadata for a specific Fedora repository, but you only
13 know its Koji tag. 13​ know its Koji tag.
14parameters: 14​parameters:
15 koji_tag: 15​ koji_tag:
16 required: true 16​ required: true
17 description: | 17​ description: |
18 name of the Koji tag, e.g. `f20`, `f20-updates`, `f20-updates-testing`, 18​ name of the Koji tag, e.g. ``f20``, ``f20-updates``,
19 or `rawhide`. 19​ ``f20-updates-testing``, or ``rawhide``.
20 20​
21 If the tag ends with `-pending` suffix, this suffix is stripped (because 21​ If the tag ends with ``-pending`` suffix, this suffix is stripped (because
22 pending tags are not real repositories), and the resulting tag is used. 22​ pending tags are not real repositories), and the resulting tag is used.
23 type: str 23​ type: str
24 arch: 24​ arch:
25 required: true 25​ required: true
26 description: list of architectures. In this list, all "meta architectures" 26​ description: list of architectures. In this list, all "meta architectures"
27 like `all`, `src` and `noarch` are ignored, and only a single "real 27​ like ``all``, ``src`` and ``noarch`` are ignored, and only a single "real
28 architecture" is expected there (e.g. `x86_64` or `i386`). 28​ architecture" is expected there (e.g. ``x86_64`` or ``i386``).
29 type: list of str 29​ type: list of str
30returns: | 30​returns: |
31 A dictionary. One of the keys is ``koji_tag`` and URL for the respective 31​ A dictionary. One of the keys is ``koji_tag`` and URL for the respective
32 repository is its value. 32​ repository is its value.
33 33​
34 If the repository in question has some parent repositories (e.g. 34​ If the repository in question has some parent repositories (e.g.
35 ``f20-updates`` is a child of ``f20``), all its parents names and their 35​ ``f20-updates`` is a child of ``f20``), all its parents names and their
36 repository URLs are returned in the dictionary as well as additional keys. 36​ repository URLs are returned in the dictionary as well as additional keys.
▲ Show 20 Lines • Show All 88 Lines • Show Last 20 Lines