1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
# Copyright 2014-2015 ARM Limited
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
This module contains utilities for generating user documentation for Workload
Automation Extensions.
"""
import re
import inspect
PARAGRAPH_SEP = re.compile(r'\n\n+')
LINE_START = re.compile(r'\n\s*')
def get_paragraphs(text):
"""returns a list of paragraphs contained in the text"""
return [LINE_START.sub(' ', p) for p in PARAGRAPH_SEP.split(text)]
class ExtensionDocumenter(object):
@property
def name(self):
return self.ext.name
@property
def summary(self):
"""Returns the summary description for this Extension, which, by
convention, is the first paragraph of the description."""
return get_paragraphs(self.description)[0]
@property
def description(self):
"""
The description for an extension is specified in the ``description``
attribute, or (legacy) as a docstring for the extension's class. If
neither method is used in the Extension, an empty string is returned.
Description is assumed to be formed as reStructuredText. Leading and
trailing whitespace will be stripped away.
"""
if hasattr(self.ext, 'description'):
return self.ext.description.strip()
elif self.ext.__class__.__doc__:
return self.ext.__class__.__doc__.strip()
else:
return ''
@property
def parameters(self):
return [ExtensionParameterDocumenter(p) for p in self.ext.parameters]
def __init__(self, ext):
self.ext = ext
class ExtensionParameterDocumenter(object):
@property
def name(self):
return self.param.name
@property
def kind(self):
return self.param.get_type_name()
@property
def default(self):
return self.param.default
@property
def description(self):
return self.param.description
@property
def constraint(self):
constraints = []
if self.param.allowed_values:
constraints.append('value must be in {}'.format(self.param.allowed_values))
if self.param.constraint:
constraint_text = self.param.constraint.__name__
if constraint_text == '<lambda>':
constraint_text = _parse_lambda(inspect.getsource(self.param.constraint))
constraints.append(constraint_text)
return ' and '.join(constraints)
def __init__(self, param):
self.param = param
# Utility functions
def _parse_lambda(text):
"""Parse the definition of a lambda function in to a readable string."""
text = text.split('lambda')[1]
param, rest = text.split(':')
param = param.strip()
# There are three things that could terminate a lambda: an (unparenthesized)
# comma, a new line and an (unmatched) close paren.
term_chars = [',', '\n', ')']
func_text = ''
inside_paren = 0 # an int rather than a bool to keep track of nesting
for c in rest:
if c in term_chars and not inside_paren:
break
elif c == ')': # must be inside paren
inside_paren -= 1
elif c == '(':
inside_paren += 1
func_text += c
# Rename the lambda parameter to 'value' so that the resulting
# "description" makes more sense.
func_text = re.sub(r'\b{}\b'.format(param), 'value', func_text)
return func_text
|
