def make_docfields(self, field_group, field_comment_option):
docfields = StringList([u''])
for field in field_group.fields:
field_type = self.constant_name if field.value else self.field_name
name = field.name + field.size
desc = field.get_description(field_comment_option)
if len(desc) == 0:
docfields.append(u':{0} {1}:'.format(field_type, name),
source=field.source,
offset=field.offset)
elif len(desc) == 1:
docfields.append(u':{0} {1}: {2}'.format(
field_type, name, desc[0].strip()),
source=desc.source(0),
offset=desc.offset(0))
elif len(desc) > 1:
if 'quote' in field_comment_option:
align_strings(desc, ' | ')
else:
align_strings(desc, ' ')
docfields.append(u':{0} {1}: {2}'.format(
field_type, name, desc[0]),
source=desc.source(0),
offset=desc.offset(0))
docfields.extend(desc[1:])
docfields.append(u':{0}-{1} {2}: {3}'.format(
field_type, TYPE_SUFFIX, name, field.type),
source=field.source,
offset=field.offset)
if field.value:
docfields.append(u':{0}-{1} {2}: {3}'.format(
field_type, VALUE_SUFFIX, name, field.value),
source=field.source,
offset=field.offset)
return docfields
def _merge_directives(directives: List[StringList]) -> StringList:
"""
The last directive heading will be used to represent the heading for the entire
group of directives.
Args:
directives (list(StringList)): The list of directives to merge.
Returns:
StringList: One directive
"""
merged_heading = StringList()
merged_directive = StringList()
merged_options = StringList()
for directive in directives:
options, _, _ = directive.get_indented(1,
until_blank=True,
strip_indent=False)
if options:
merged_options.extend(options)
del directive[1:1 + len(options)]
directive_heading = directive[0]
del directive[0]
merged_directive.extend(directive)
merged_heading = directive_heading
merged_directive.insert(0, merged_options)
merged_directive.insert(0,
merged_heading,
source=merged_directive.source(0))
return merged_directive
def make_docfields(self, field_group, field_comment_option):
docfields = StringList([u''])
for field in field_group.fields:
field_type = self.constant_name if field.value else self.field_name
name = field.name + field.size
desc = field.get_description(field_comment_option)
if len(desc) == 0:
docfields.append(u':{0} {1}:'.format(field_type, name),
source=field.source, offset=field.offset)
elif len(desc) == 1:
docfields.append(u':{0} {1}: {2}'.format(field_type,
name,
desc[0].strip()),
source=desc.source(0), offset=desc.offset(0))
elif len(desc) > 1:
if 'quote' in field_comment_option:
align_strings(desc, ' | ')
else:
align_strings(desc, ' ')
docfields.append(u':{0} {1}: {2}'.format(field_type,
name, desc[0]),
source=desc.source(0), offset=desc.offset(0))
docfields.extend(desc[1:])
docfields.append(u':{0}-{1} {2}: {3}'.format(field_type,
TYPE_SUFFIX,
name,
field.type),
source=field.source, offset=field.offset)
if field.value:
docfields.append(u':{0}-{1} {2}: {3}'.format(field_type,
VALUE_SUFFIX,
name,
field.value),
source=field.source, offset=field.offset)
return docfields
def make_docfields(self, field_groups, field_comment_option):
docfields = StringList()
for field_group_type, field_group in zip(self.field_group_types,
field_groups):
docfields.extend(
field_group_type.make_docfields(field_group,
field_comment_option))
return docfields
def make_docfields(self, field_groups, field_comment_option):
docfields = StringList()
for field_group_type, field_group in zip(self.field_group_types,
field_groups):
docfields.extend(
field_group_type.make_docfields(field_group,
field_comment_option))
return docfields
def _translate_into_tab_demo(block_text: str) -> StringList:
md, rst = _split_by_language(block_text)
string_list = StringList()
string_list.extend(_rst_demo(rst))
string_list.extend(_md_demo(md))
return string_list
def join_blocks(blocks):
u"""Join list of StringList to single StringList
"""
strings = StringList()
for block in blocks:
strings.extend(block)
strings.extend(StringList([u''])) # insert a blank line
# remove the last blank line
if strings and not strings[-1]:
del strings[-1]
return strings
def join_blocks(blocks):
u"""Join list of StringList to single StringList
"""
strings = StringList()
for block in blocks:
strings.extend(block)
strings.extend(StringList([u''])) # insert a blank line
# remove the last blank line
if strings and not strings[-1]:
del strings[-1]
return strings
def parse_stage(self, stage: Stage, idt: int = 0) -> StringList:
head = self.tpl_stage.format(name=stage.name)
if stage.lineno:
head += "\n"
head += self.tpl_source.format(
filename=relpath(stage.filename),
lineno=self.workflow.linemaps[stage.filename][stage.lineno],
)
head = indent(head, " " * idt)
headlines = head.splitlines()
doc = self.parse_doc(stage.docstring, stage.filename, idt + 3)
res = StringList(headlines, stage.filename) + doc
for rule in sorted(stage.rules, key=lambda s: s.name):
res.extend(self.parse_rule(rule, idt + 3))
return res
def _generate_nodes(self) -> List[nodes.Node]:
"""Generate Sphinx nodes from parsed snakefile"""
node = nodes.paragraph('')
result = StringList()
# generate stages
stages = Stage.get_registry().values()
stages = list(set(stages))
stages = sorted(stages, key=lambda x: x.name)
for stage in stages:
result.extend(self.parse_stage(stage))
# generate nodes for rules not registered with stages
rules = self.workflow.rules
for rule in rules:
if not getattr(rule, "ymp_stage", False):
result.extend(self.parse_rule(rule.name))
self.state.nested_parse(result, 0, node)
return [node]
def update_content(self):
package_name = self.arguments[0]
package = self.find_package(package_name)
if not package:
return None
self.env.note_dependency(self.env.relfn2path(package.filename)[0])
content = StringList()
for attr in self.env.config.ros_package_attrs:
if attr in self.env.config.ros_package_attrs_formatter:
formatter = self.env.config.ros_package_attrs_formatter[attr]
elif attr.endswith('_depends'):
formatter = 'depend_formatter'
else:
formatter = self.attr_formatters.get(attr, 'default_formatter')
field = format_attr(package, attr, formatter)
if field:
content.extend(field)
content.items = [(source, 0) for source, line in content.items]
if len(content) > 0:
content.append(StringList([u'']))
return content + self.content
def update_content(self):
package_name = self.arguments[0]
package = self.find_package(package_name)
if not package:
return None
self.env.note_dependency(self.env.relfn2path(package.filename)[0])
content = StringList()
for attr in self.env.config.ros_package_attrs:
if attr in self.env.config.ros_package_attrs_formatter:
formatter = self.env.config.ros_package_attrs_formatter[attr]
elif attr.endswith('_depends'):
formatter = 'depend_formatter'
else:
formatter = self.attr_formatters.get(attr, 'default_formatter')
field = format_attr(package, attr, formatter)
if field:
content.extend(field)
content.items = [(source, 0) for source, line in content.items]
if len(content) > 0:
content.append(StringList([u'']))
return content + self.content
def update_content(self):
package_name, type_name = self.arguments[0].split('/', 1)
package = self.find_package(package_name)
if not package:
return
file_path, file_content \
= self.type_file.read(os.path.dirname(package.filename),
type_name)
if file_content is None:
self.state_machine.reporter.warning(
'cannot find file {0}'.format(file_path), line=self.lineno)
return
type_relfile = os.path.relpath(file_path, self.env.srcdir)
self.env.note_dependency(type_relfile)
field_groups = self.type_file.parse(file_content, package_name)
# fields
options = self.options.get('field-comment', '')
field_comment_option = options.encode('ascii').lower().split()
content = self.type_file.make_docfields(field_groups,
field_comment_option)
# description
if field_groups:
desc = field_groups[0].description
desc_blocks = split_blocks(desc)
if desc_blocks:
description_option = [
x.strip() for x in self.options.get('description',
'').lower().split(',')
]
first = second = None
for option in description_option:
if not option: # ignore empty option
pass
elif ':' in option:
first, second = option.split(':', 1)
elif option == 'quote':
pass
else:
raise ValueError(
"unkonwn option {0} in "
"the description option".format(option))
blocks = desc_blocks[(int(first) if first else None):(
int(second) if second else None)]
if blocks:
description = join_blocks(blocks)
if 'quote' in description_option:
align_strings(description, '| ')
else:
align_strings(description)
content = content + StringList([u'']) + description
content = content + self.content
# raw file content
raw_option = self.options.get('raw', None)
#
if raw_option is not None:
code_block = StringList([u'', u'.. code-block:: rostype', u''])
code_block.extend(
StringList([' ' + l for l in file_content.data],
items=file_content.items))
if raw_option == 'head':
content = code_block + StringList([u'']) + content
elif raw_option == 'tail':
content = content + code_block
return content
def run(self):
config = self.state.document.settings.env.config
# Read enabled builders; Defaults to None
chosen_builders = choose_builders(self.arguments)
# Enable 'http' language for http part
self.arguments = ['http']
# process 'query' reST fields
if self.content:
raw = ('\r\n'.join(self.content)).encode('utf-8')
request = parsers.parse_request(raw)
params, _ = request.extract_fields('query')
params = [(p[1], p[2]) for p in params]
new_path = utils.add_url_params(request.path, params)
self.content[0] = ' '.join(
[request.command, new_path, request.request_version])
# split the request and optional response in the content.
# The separator is two empty lines followed by a line starting with
# 'HTTP/' or 'HTTP '
request_content = StringList()
request_content_no_fields = StringList()
response_content = None
emptylines_count = 0
in_response = False
is_field = r':({}) (.+): (.+)'.format('|'.join(AVAILABLE_FIELDS))
for i, line in enumerate(self.content):
source = self.content.source(i)
if in_response:
response_content.append(line, source)
else:
if emptylines_count >= 2 and \
(line.startswith('HTTP/') or line.startswith('HTTP ')):
in_response = True
response_content = StringList()
response_content.append(line, source)
elif line == '':
emptylines_count += 1
else:
request_content.extend(
StringList([''] * emptylines_count, source))
request_content.append(line, source)
if not re.match(is_field, line):
request_content_no_fields.extend(
StringList([''] * emptylines_count, source))
request_content_no_fields.append(line, source)
emptylines_count = 0
# Load optional external request
cwd = os.path.dirname(self.state.document.current_source)
if 'request' in self.options:
request = utils.resolve_path(self.options['request'], cwd)
with open(request) as fp:
request_content = request_content_no_fields = StringList(
list(map(str.rstrip, fp.readlines())), request)
# Load optional external response
if 'response' in self.options:
response = utils.resolve_path(self.options['response'], cwd)
with open(response) as fp:
response_content = StringList(
list(map(str.rstrip, fp.readlines())), response)
# reset the content to the request, stripped of the reST fields
self.content = request_content_no_fields
# Wrap and render main directive as 'http-example-http'
klass = 'http-example-http'
container = nodes.container('', classes=[klass])
container.append(nodes.caption('', 'http'))
container.extend(super(HTTPExample, self).run())
# Init result node list
result = [container]
# reset the content to just the request
self.content = request_content
# Append builder responses
if request_content_no_fields:
raw = ('\r\n'.join(request_content_no_fields)).encode('utf-8')
for name in chosen_builders:
request = parsers.parse_request(raw, config.httpexample_scheme)
builder_, language = AVAILABLE_BUILDERS[name]
command = builder_(request)
content = StringList([command],
request_content_no_fields.source(0))
options = self.options.copy()
options.pop('name', None)
options.pop('caption', None)
block = CodeBlock('code-block', [language], options, content,
self.lineno, self.content_offset,
self.block_text, self.state,
self.state_machine)
# Wrap and render main directive as 'http-example-{name}'
klass = 'http-example-{}'.format(name)
container = nodes.container('', classes=[klass])
container.append(nodes.caption('', name))
container.extend(block.run())
# Append to result nodes
result.append(container)
# Append optional response
if response_content:
options = self.options.copy()
options.pop('name', None)
options.pop('caption', None)
block = CodeBlock('code-block', ['http'], options,
response_content, self.lineno,
self.content_offset, self.block_text, self.state,
self.state_machine)
# Wrap and render main directive as 'http-example-response'
klass = 'http-example-response'
container = nodes.container('', classes=[klass])
container.append(nodes.caption('', 'response'))
container.extend(block.run())
# Append to result nodes
result.append(container)
# Final wrap
container_node = nodes.container('', classes=['http-example'])
container_node.extend(result)
return [container_node]
def update_content(self):
package_name, type_name = self.arguments[0].split('/', 1)
package = self.find_package(package_name)
if not package:
return
file_path, file_content \
= self.type_file.read(os.path.dirname(package.filename),
type_name)
if file_content is None:
self.state_machine.reporter.warning(
'cannot find file {0}'.format(file_path),
line=self.lineno)
return
type_relfile = os.path.relpath(file_path, self.env.srcdir)
self.env.note_dependency(type_relfile)
field_groups = self.type_file.parse(file_content, package_name)
# fields
options = self.options.get('field-comment', '')
field_comment_option = options.encode('ascii').lower().split()
content = self.type_file.make_docfields(field_groups,
field_comment_option)
# description
if field_groups:
desc = field_groups[0].description
desc_blocks = split_blocks(desc)
if desc_blocks:
description_option = [x.strip() for x in
self.options.get('description', '').
lower().split(',')]
first = second = None
for option in description_option:
if not option: # ignore empty option
pass
elif ':' in option:
first, second = option.split(':', 1)
elif option == 'quote':
pass
else:
raise ValueError(
"unkonwn option {0} in "
"the description option".format(option))
blocks = desc_blocks[(int(first) if first else None):
(int(second) if second else None)]
if blocks:
description = join_blocks(blocks)
if 'quote' in description_option:
align_strings(description, '| ')
else:
align_strings(description)
content = content + StringList([u'']) + description
content = content + self.content
# raw file content
raw_option = self.options.get('raw', None)
#
if raw_option is not None:
code_block = StringList([u'', u'.. code-block:: rostype', u''])
code_block.extend(StringList([' '+l for l in file_content.data],
items=file_content.items))
if raw_option == 'head':
content = code_block + StringList([u'']) + content
elif raw_option == 'tail':
content = content + code_block
return content
def run(self):
config = self.state.document.settings.env.config
# Read enabled builders; Defaults to None
if self.arguments:
chosen_builders = choose_builders(self.arguments)
else:
chosen_builders = []
# Enable 'http' language for http part
self.arguments = ['http']
# split the request and optional response in the content.
# The separator is two empty lines followed by a line starting with
# 'HTTP/'
request_content = StringList()
response_content = None
emptylines_count = 0
in_response = False
for i, line in enumerate(self.content):
source = self.content.source(i)
if in_response:
response_content.append(line, source)
else:
if emptylines_count >= 2 and line.startswith('HTTP/'):
in_response = True
response_content = StringList()
response_content.append(line, source)
elif line == '':
emptylines_count += 1
else:
request_content.extend(
StringList([''] * emptylines_count, source))
emptylines_count = 0
request_content.append(line, source)
# Load optional external request
cwd = os.path.dirname(self.state.document.current_source)
if 'request' in self.options:
request = utils.resolve_path(self.options['request'], cwd)
with open(request) as fp:
request_content = StringList(
list(map(str.rstrip, fp.readlines())), request)
# Load optional external response
if 'response' in self.options:
response = utils.resolve_path(self.options['response'], cwd)
with open(response) as fp:
response_content = StringList(
list(map(str.rstrip, fp.readlines())), response)
# reset the content to just the request
self.content = request_content
# Wrap and render main directive as 'http-example-http'
klass = 'http-example-http'
container = nodes.container('', classes=[klass])
container.append(nodes.caption('', 'http'))
container.extend(super(HTTPExample, self).run())
# Init result node list
result = [container]
# Append builder responses
for name in chosen_builders:
raw = ('\r\n'.join(request_content)).encode('utf-8')
request = parsers.parse_request(raw, config.httpexmpl_scheme)
builder_, language = AVAILABLE_BUILDERS[name]
command = builder_(request)
content = StringList([command], request_content.source(0))
options = self.options.copy()
options.pop('name', None)
options.pop('caption', None)
block = CodeBlock(
'code-block',
[language],
options,
content,
self.lineno,
self.content_offset,
self.block_text,
self.state,
self.state_machine
)
# Wrap and render main directive as 'http-example-{name}'
klass = 'http-example-{}'.format(name)
container = nodes.container('', classes=[klass])
container.append(nodes.caption('', name))
container.extend(block.run())
# Append to result nodes
result.append(container)
# Append optional response
if response_content:
options = self.options.copy()
options.pop('name', None)
options.pop('caption', None)
block = CodeBlock(
'code-block',
['http'],
options,
response_content,
self.lineno,
self.content_offset,
self.block_text,
self.state,
self.state_machine
)
# Wrap and render main directive as 'http-example-response'
klass = 'http-example-response'
container = nodes.container('', classes=[klass])
container.append(nodes.caption('', 'response'))
container.extend(block.run())
# Append to result nodes
result.append(container)
# Final wrap
container_node = nodes.container('', classes=['http-example'])
container_node.extend(result)
return [container_node]
def make_docfields(self, all_fields, field_comment_option):
docfields = StringList()
for field_group, fields in zip(self.groups, all_fields):
docfields.extend(field_group.make_docfields(fields,
field_comment_option))
return docfields
