class StepsOutput(object):
"""
Base class for rendered step form. The render() method generates the rst in
the internal RstCloth object.
"""
def __init__(self, steps, conf=None):
if not isinstance(steps, Steps):
raise TypeError
else:
self.steps = steps
self.conf = lazy_conf(conf)
self.current_step = 1
self.rst = RstCloth()
self.hook()
def hook(self):
self.indent = 3
def edition_check(self, step):
if 'edition' in step:
if 'edition' in self.conf.project:
if step['edition'] != self.conf.project.edition:
return False
else:
return True
@staticmethod
def annotate_optional(step):
if 'optional' in step and step['optional'] is True:
if isinstance(step['title'], dict):
step['title']['text'] = 'Optional. ' + step['title']['text']
else:
if 'title' in step:
step['title'] = 'Optional. ' + step['title']
elif 'heading' in step:
step['heading'] = 'Optional. ' + step['heading']
del step['optional']
return step
else:
return step
def render(self):
for step in self.steps.source_list:
if self.edition_check(step) is False:
continue
step = self.annotate_optional(step)
self.heading(step)
self.pre(step)
self.current_step = step['stepnum']
if 'action' in step:
if isinstance(step['action'], list):
for block in step['action']:
self.code_step(block)
else:
self.code_step(step['action'])
self.content(step)
self.post(step)
def content(self, doc):
if 'content' in doc and doc['content'] is not None:
self.rst.content(doc['content'], wrap=False, indent=self.indent)
self.rst.newline()
def pre(self, doc):
if 'pre' in doc and doc['pre'] is not None:
self.rst.content(doc['pre'], wrap=False, indent=self.indent)
self.rst.newline()
def post(self, doc, code_step=False):
if 'post' in doc and doc['post'] is not None:
self.rst.content(doc['post'], wrap=False, indent=self.indent)
self.rst.newline()
if code_step is False:
self.post_step_hook()
def post_step_hook(self):
pass
def _heading(self, block, override_char=None, indent=0):
if 'heading' in block:
if isinstance(block['heading'], dict):
if 'character' in block['heading']:
pass
else:
block['heading']['character'] = override_char
else:
block['heading'] = { 'text': block['heading'],
'character': override_char }
if block['heading']['text'] is None:
logger.error('step in "{0}" is missing a heading'.format(os.path.basename(self.steps.source_fn)))
return
self.rst.heading(text=block['heading']['text'],
char=block['heading']['character'],
indent=indent)
self.rst.newline()
def code_step(self, block):
if 'code' in block and 'content' in block:
raise InvalidStep
if 'heading' in block:
self.block_heading(block)
self.pre(block)
if 'code' in block:
if 'language' not in block:
block['language'] = 'none'
if not isinstance(block['code'], list):
block['code'] = block['code'].split('\n')
self.rst.directive(name='code-block',
arg=block['language'],
content=block['code'],
indent=self.indent)
self.rst.newline()
if 'content' in block:
self.content(block['content'])
self.post(block, code_step=True)
def key_name(self):
key_name = os.path.splitext(os.path.basename(self.steps.source_fn))[0]
if key_name.startswith('step-') or key_name.startswith('steps-'):
key_name = key_name.split('-', 1)[1]
return key_name
def build_page(data, conf):
fn = os.path.join(conf.paths.projectroot,
conf.paths.includes,
'metadata.yaml')
if not os.path.exists(fn):
return None
else:
iconf = BuildConfiguration(fn)
r = RstCloth()
r.title(iconf.title)
r.newline()
r.directive('default-domain', iconf.domain)
r.newline()
if 'introduction' in iconf:
r.content(iconf.introduction)
r.newline()
r.directive(name='contents', arg='Included Files',
fields=[ ('backlinks', 'none'),
('class', 'long-toc'),
('depth', 1),
('local', ''),
])
r.newline()
data = data.items()
data.sort()
for _, record in data:
page_name = r.pre(record['name'])
r.heading(text=page_name, char='-', indent=0)
r.newline()
r.heading('Meta', char='~', indent=0)
r.newline()
if record['num_clients'] == 0:
r.content('{0} is not included in any files.'.format(page_name))
r.newline()
add_content(r, record)
elif record['num_clients'] == 1:
if record['yaml_only']:
r.content('{0} is only included in yaml files.'.format(page_name))
r.newline()
else:
link = r.role('doc', record['clients'][0])
r.content('{0} is only included in {1}.'.format(page_name, link))
r.newline()
add_meta(r, page_name, record)
add_content(r, record)
else:
r.content('{0} is included in **{1}** files.'.format(page_name, record['num_clients']),
wrap=False)
r.newline()
add_meta(r, page_name, record)
if record['yaml_only'] is False:
clients = [ p for p in
record['clients']
if not p.startswith('/includes')
]
if len(clients) == 1:
client_link = r.role('doc', clients[0])
inc_str = '{0} is the only file that includes {1} that is not also an include.'
r.content(inc_str.format(client_link, page_name))
r.newline()
else:
r.heading('Client Pages', char='~', indent=0)
r.newline()
for pg in clients:
client_link = r.role('doc', pg)
r.li(client_link, wrap=False)
r.newline()
add_include_example(r, page_name, record['path'])
add_content(r, record)
return r
class StepsOutput(object):
"""
Base class for rendered step form. The render() method generates the rst in
the internal RstCloth object.
"""
def __init__(self, steps, conf=None):
if not isinstance(steps, Steps):
raise TypeError
else:
self.steps = steps
self.conf = lazy_conf(conf)
self.current_step = 1
self.rst = RstCloth()
self.hook()
def hook(self):
self.indent = 3
def edition_check(self, step):
if 'edition' in step:
if 'edition' in self.conf.project:
if step['edition'] != self.conf.project.edition:
return False
else:
return True
@staticmethod
def annotate_optional(step):
if 'optional' in step and step['optional'] is True:
if isinstance(step['title'], dict):
step['title']['text'] = 'Optional. ' + step['title']['text']
else:
if 'title' in step:
step['title'] = 'Optional. ' + step['title']
elif 'heading' in step:
step['heading'] = 'Optional. ' + step['heading']
del step['optional']
return step
else:
return step
def render(self):
for step in self.steps.source_list:
if self.edition_check(step) is False:
continue
step = self.annotate_optional(step)
self.heading(step)
self.pre(step)
self.current_step = step['stepnum']
if 'action' in step:
if isinstance(step['action'], list):
for block in step['action']:
self.code_step(block)
else:
self.code_step(step['action'])
self.content(step)
self.post(step)
def content(self, doc):
if 'content' in doc and doc['content'] is not None:
self.rst.content(doc['content'], wrap=False, indent=self.indent)
self.rst.newline()
def pre(self, doc):
if 'pre' in doc and doc['pre'] is not None:
self.rst.content(doc['pre'], wrap=False, indent=self.indent)
self.rst.newline()
def post(self, doc, code_step=False):
if 'post' in doc and doc['post'] is not None:
self.rst.content(doc['post'], wrap=False, indent=self.indent)
self.rst.newline()
if code_step is False:
self.post_step_hook()
def post_step_hook(self):
pass
def _heading(self, block, override_char=None, indent=0):
if 'heading' in block:
if isinstance(block['heading'], dict):
if 'character' in block['heading']:
pass
else:
block['heading']['character'] = override_char
else:
block['heading'] = {
'text': block['heading'],
'character': override_char
}
if block['heading']['text'] is None:
logger.error('step in "{0}" is missing a heading'.format(
os.path.basename(self.steps.source_fn)))
return
self.rst.heading(text=block['heading']['text'],
char=block['heading']['character'],
indent=indent)
self.rst.newline()
def code_step(self, block):
if 'code' in block and 'content' in block:
raise InvalidStep
if 'heading' in block:
self.block_heading(block)
self.pre(block)
if 'code' in block:
if 'language' not in block:
block['language'] = 'none'
if not isinstance(block['code'], list):
block['code'] = block['code'].split('\n')
self.rst.directive(name='code-block',
arg=block['language'],
content=block['code'],
indent=self.indent)
self.rst.newline()
if 'content' in block:
self.content(block['content'])
self.post(block, code_step=True)
def key_name(self):
key_name = os.path.splitext(os.path.basename(self.steps.source_fn))[0]
if key_name.startswith('step-') or key_name.startswith('steps-'):
key_name = key_name.split('-', 1)[1]
return key_name
def build_page(data, conf):
fn = os.path.join(conf.paths.projectroot, conf.paths.includes,
'metadata.yaml')
if not os.path.exists(fn):
return None
else:
iconf = BuildConfiguration(fn)
r = RstCloth()
r.title(iconf.title)
r.newline()
r.directive('default-domain', iconf.domain)
r.newline()
if 'introduction' in iconf:
r.content(iconf.introduction)
r.newline()
r.directive(name='contents',
arg='Included Files',
fields=[
('backlinks', 'none'),
('class', 'long-toc'),
('depth', 1),
('local', ''),
])
r.newline()
data = data.items()
data.sort()
for _, record in data:
page_name = r.pre(record['name'])
r.heading(text=page_name, char='-', indent=0)
r.newline()
r.heading('Meta', char='~', indent=0)
r.newline()
if record['num_clients'] == 0:
r.content('{0} is not included in any files.'.format(page_name))
r.newline()
add_content(r, record)
elif record['num_clients'] == 1:
if record['yaml_only']:
r.content(
'{0} is only included in yaml files.'.format(page_name))
r.newline()
else:
link = r.role('doc', record['clients'][0])
r.content('{0} is only included in {1}.'.format(
page_name, link))
r.newline()
add_meta(r, page_name, record)
add_content(r, record)
else:
r.content('{0} is included in **{1}** files.'.format(
page_name, record['num_clients']),
wrap=False)
r.newline()
add_meta(r, page_name, record)
if record['yaml_only'] is False:
clients = [
p for p in record['clients']
if not p.startswith('/includes')
]
if len(clients) == 1:
client_link = r.role('doc', clients[0])
inc_str = '{0} is the only file that includes {1} that is not also an include.'
r.content(inc_str.format(client_link, page_name))
r.newline()
else:
r.heading('Client Pages', char='~', indent=0)
r.newline()
for pg in clients:
client_link = r.role('doc', pg)
r.li(client_link, wrap=False)
r.newline()
add_include_example(r, page_name, record['path'])
add_content(r, record)
return r
def build_page(data, conf):
fn = os.path.join(conf.paths.projectroot, conf.paths.includes, "metadata.yaml")
if not os.path.exists(fn):
return None
else:
iconf = BuildConfiguration(fn)
r = RstCloth()
r.title(iconf.title)
r.newline()
r.directive("default-domain", iconf.domain)
r.newline()
if "introduction" in iconf:
r.content(iconf.introduction)
r.newline()
r.directive(
name="contents",
arg="Included Files",
fields=[("backlinks", "none"), ("class", "long-toc"), ("depth", 1), ("local", "")],
)
r.newline()
data = data.items()
data.sort()
for _, record in data:
page_name = r.pre(record["name"])
r.heading(text=page_name, char="-", indent=0)
r.newline()
r.heading("Meta", char="~", indent=0)
r.newline()
if record["num_clients"] == 0:
r.content("{0} is not included in any files.".format(page_name))
r.newline()
add_content(r, record)
elif record["num_clients"] == 1:
if record["yaml_only"]:
r.content("{0} is only included in yaml files.".format(page_name))
r.newline()
else:
link = r.role("doc", record["clients"][0])
r.content("{0} is only included in {1}.".format(page_name, link))
r.newline()
add_meta(r, page_name, record)
add_content(r, record)
else:
r.content("{0} is included in **{1}** files.".format(page_name, record["num_clients"]), wrap=False)
r.newline()
add_meta(r, page_name, record)
if record["yaml_only"] is False:
clients = [p for p in record["clients"] if not p.startswith("/includes")]
if len(clients) == 1:
client_link = r.role("doc", clients[0])
inc_str = "{0} is the only file that includes {1} that is not also an include."
r.content(inc_str.format(client_link, page_name))
r.newline()
else:
r.heading("Client Pages", char="~", indent=0)
r.newline()
for pg in clients:
client_link = r.role("doc", pg)
r.li(client_link, wrap=False)
r.newline()
add_include_example(r, page_name, record["path"])
add_content(r, record)
return r
