Adding upstream version 2.7.upstream/2.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 408 insertions, 0 deletions

diff --git a/docs/source/powerline_automan.py b/docs/source/powerline_automan.py
new file mode 100644
index 0000000..85d241c
--- /dev/null
+++ b/docs/source/powerline_automan.py
@@ -0,0 +1,408 @@
+# vim:fileencoding=utf-8:noet
+from __future__ import (unicode_literals, division, absolute_import, print_function)
+
+import os
+import re
+import codecs
+
+from collections import namedtuple
+from argparse import REMAINDER
+
+from functools import reduce
+
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst.directives import unchanged_required
+from docutils import nodes
+
+from powerline.lib.unicode import u
+
+
+AUTHOR_LINE_START = '* `'
+GLYPHS_AUTHOR_LINE_START = '* The glyphs in the font patcher are created by '
+
+
+def get_authors():
+	credits_file = os.path.join(os.path.dirname(__file__), 'license-and-credits.rst')
+	authors = []
+	glyphs_author = None
+	with codecs.open(credits_file, encoding='utf-8') as CF:
+		section = None
+		prev_line = None
+		for line in CF:
+			line = line[:-1]
+			if line and not line.replace('-', ''):
+				section = prev_line
+			elif section == 'Authors':
+				if line.startswith(AUTHOR_LINE_START):
+					authors.append(line[len(AUTHOR_LINE_START):line.index('<')].strip())
+			elif section == 'Contributors':
+				if line.startswith(GLYPHS_AUTHOR_LINE_START):
+					assert(not glyphs_author)
+					glyphs_author = line[len(GLYPHS_AUTHOR_LINE_START):line.index(',')].strip()
+			prev_line = line
+	return {
+		'authors': ', '.join(authors),
+		'glyphs_author': glyphs_author,
+	}
+
+
+class AutoManSubparsers(object):
+	def __init__(self):
+		self.parsers = []
+
+	def add_parser(self, command, *args, **kwargs):
+		self.parsers.append((command, AutoManParser(*args, **kwargs)))
+		return self.parsers[-1][1]
+
+
+Argument = namedtuple('Argument', ('names', 'help', 'choices', 'metavar', 'required', 'nargs', 'is_option', 'is_long_option', 'is_short_option', 'multi', 'can_be_joined'))
+
+
+def parse_argument(*args, **kwargs):
+	is_option = args[0].startswith('-')
+	is_long_option = args[0].startswith('--')
+	is_short_option = is_option and not is_long_option
+	action = kwargs.get('action', 'store')
+	multi = kwargs.get('action') in ('append',) or kwargs.get('nargs') is REMAINDER
+	nargs = kwargs.get('nargs', (1 if action in ('append', 'store') else 0))
+	return Argument(
+		names=args,
+		help=u(kwargs.get('help', '')),
+		choices=[str(choice) for choice in kwargs.get('choices', [])],
+		metavar=kwargs.get('metavar') or args[-1].lstrip('-').replace('-', '_').upper(),
+		required=kwargs.get('required', False) if is_option else (
+			kwargs.get('nargs') not in ('?',)),
+		nargs=nargs,
+		multi=multi,
+		is_option=is_option,
+		is_long_option=is_long_option,
+		is_short_option=is_short_option,
+		can_be_joined=(is_short_option and not multi and not nargs)
+	)
+
+
+class AutoManGroup(object):
+	is_short_option = False
+	is_option = False
+	is_long_option = False
+	can_be_joined = False
+
+	def __init__(self):
+		self.arguments = []
+		self.required = False
+
+	def add_argument(self, *args, **kwargs):
+		self.arguments.append(parse_argument(*args, **kwargs))
+
+	def add_argument_group(self, *args, **kwargs):
+		self.arguments.append(AutoManGroup())
+		return self.arguments[-1]
+
+
+class SurroundWith():
+	def __init__(self, ret, condition, start='[', end=']'):
+		self.ret = ret
+		self.condition = condition
+		self.start = start
+		self.end = end
+
+	def __enter__(self, *args):
+		if self.condition:
+			self.ret.append(nodes.Text(self.start))
+
+	def __exit__(self, *args):
+		if self.condition:
+			self.ret.append(nodes.Text(self.end))
+
+
+def insert_separators(ret, sep):
+	for i in range(len(ret) - 1, 0, -1):
+		ret.insert(i, nodes.Text(sep))
+	return ret
+
+
+def format_usage_arguments(arguments, base_length=None):
+	line = []
+	prev_argument = None
+	arg_indexes = [0]
+	arguments = arguments[:]
+	while arguments:
+		argument = arguments.pop(0)
+		if isinstance(argument, nodes.Text):
+			line += [argument]
+			continue
+		can_join_arguments = (
+			argument.is_short_option
+			and prev_argument
+			and prev_argument.can_be_joined
+			and prev_argument.required == argument.required
+		)
+		if (
+			prev_argument
+			and not prev_argument.required
+			and prev_argument.can_be_joined
+			and not can_join_arguments
+		):
+			line.append(nodes.Text(']'))
+		arg_indexes.append(len(line))
+		if isinstance(argument, AutoManGroup):
+			arguments = (
+				[nodes.Text(' (')]
+				+ insert_separators(argument.arguments[:], nodes.Text(' |'))
+				+ [nodes.Text(' )')]
+				+ arguments
+			)
+		else:
+			if not can_join_arguments:
+				line.append(nodes.Text(' '))
+			with SurroundWith(line, not argument.required and not argument.can_be_joined):
+				if argument.can_be_joined and not can_join_arguments and not argument.required:
+					line.append(nodes.Text('['))
+				if argument.is_option:
+					line.append(nodes.strong())
+					name = argument.names[0]
+					if can_join_arguments:
+						name = name[1:]
+					# `--` is automatically transformed into &#8211; (EN DASH) 
+					# when parsing into HTML. We do not need this.
+					line[-1] += [nodes.Text(char) for char in name]
+				elif argument.nargs is REMAINDER:
+					line.append(nodes.Text('['))
+					line.append(nodes.strong())
+					line[-1] += [nodes.Text(char) for char in '--']
+					line.append(nodes.Text('] '))
+				if argument.nargs:
+					assert(argument.nargs in (1, '?', REMAINDER))
+					with SurroundWith(
+						line, (
+							True
+							if argument.nargs is REMAINDER
+							else (argument.nargs == '?' and argument.is_option)
+						)
+					):
+						if argument.is_long_option:
+							line.append(nodes.Text('='))
+						line.append(nodes.emphasis(text=argument.metavar))
+				elif not argument.is_option:
+					line.append(nodes.strong(text=argument.metavar))
+			if argument.multi:
+				line.append(nodes.Text('…'))
+		prev_argument = argument
+	if (
+		prev_argument
+		and prev_argument.can_be_joined
+		and not prev_argument.required
+	):
+		line.append(nodes.Text(']'))
+	arg_indexes.append(len(line))
+	ret = []
+	if base_length is None:
+		ret = line
+	else:
+		length = base_length
+		prev_arg_idx = arg_indexes.pop(0)
+		while arg_indexes:
+			next_arg_idx = arg_indexes.pop(0)
+			arg_length = sum((len(element.astext()) for element in line[prev_arg_idx:next_arg_idx]))
+			if length + arg_length > 68:
+				ret.append(nodes.Text('\n' + (' ' * base_length)))
+				length = base_length
+			ret += line[prev_arg_idx:next_arg_idx]
+			length += arg_length
+			prev_arg_idx = next_arg_idx
+	return ret
+
+
+LITERAL_RE = re.compile(r"`(.*?)'")
+
+
+def parse_argparse_text(text):
+	rst_text = LITERAL_RE.subn(r'``\1``', text)[0]
+	ret = []
+	for i, text in enumerate(rst_text.split('``')):
+		if i % 2 == 0:
+			ret.append(nodes.Text(text))
+		else:
+			ret.append(nodes.literal(text=text))
+	return ret
+
+
+def flatten_groups(arguments):
+	for argument in arguments:
+		if isinstance(argument, AutoManGroup):
+			for group_argument in flatten_groups(argument.arguments):
+				yield group_argument
+		else:
+			yield argument
+
+
+def format_arguments(arguments):
+	return [nodes.definition_list(
+		'', *[
+			nodes.definition_list_item(
+				'',
+				nodes.term(
+					# node.Text('') is required because otherwise for some 
+					# reason first name node is seen in HTML output as 
+					# `<strong>abc</strong>`.
+					'', *([nodes.Text('')] + (
+						insert_separators([
+							nodes.strong('', '', *[nodes.Text(ch) for ch in name])
+							for name in argument.names
+						], ', ')
+						if argument.is_option else
+						# Unless node.Text('') is here metavar is written in 
+						# bold in the man page.
+						[nodes.Text(''), nodes.emphasis(text=argument.metavar)]
+					) + (
+						[] if not argument.is_option or not argument.nargs else
+						[nodes.Text(' '), nodes.emphasis('', argument.metavar)]
+					))
+				),
+				nodes.definition('', nodes.paragraph('', *parse_argparse_text(argument.help or ''))),
+			)
+			for argument in flatten_groups(arguments)
+		] + [
+			nodes.definition_list_item(
+				'',
+				nodes.term(
+					'', nodes.Text(''),
+					nodes.strong(text='-h'),
+					nodes.Text(', '),
+					nodes.strong('', '', nodes.Text('-'), nodes.Text('-help')),
+				),
+				nodes.definition('', nodes.paragraph('', nodes.Text('Display help and exit.')))
+			)
+		]
+	)]
+
+
+def format_subcommand_usage(arguments, subcommands, progname, base_length):
+	return reduce((lambda a, b: a + reduce((lambda c, d: c + d), b, [])), [
+		[
+			[progname]
+			+ format_usage_arguments(arguments)
+			+ [nodes.Text(' '), nodes.strong(text=subcmd)]
+			+ format_usage_arguments(subparser.arguments)
+			+ [nodes.Text('\n')]
+			for subcmd, subparser in subparsers.parsers
+		]
+		for subparsers in subcommands
+	], [])
+
+
+def format_subcommands(subcommands):
+	return reduce((lambda a, b: a + reduce((lambda c, d: c + d), b, [])), [
+		[
+			[
+				nodes.section(
+					'',
+					nodes.title(text='Arguments specific to ' + subcmd + ' subcommand'),
+					*format_arguments(subparser.arguments),
+					ids=['subcmd-' + subcmd]
+				)
+			]
+			for subcmd, subparser in subparsers.parsers
+		]
+		for subparsers in subcommands
+	], [])
+
+
+class AutoManParser(object):
+	def __init__(self, description=None, help=None):
+		self.description = description
+		self.help = help
+		self.arguments = []
+		self.subcommands = []
+
+	def add_argument(self, *args, **kwargs):
+		self.arguments.append(parse_argument(*args, **kwargs))
+
+	def add_subparsers(self):
+		self.subcommands.append(AutoManSubparsers())
+		return self.subcommands[-1]
+
+	def add_mutually_exclusive_group(self):
+		self.arguments.append(AutoManGroup())
+		return self.arguments[-1]
+
+	def automan_usage(self, prog):
+		block = nodes.literal_block()
+		progname = nodes.strong()
+		progname += [nodes.Text(prog)]
+		base_length = len(prog)
+		if self.subcommands:
+			block += format_subcommand_usage(self.arguments, self.subcommands, progname, base_length)
+		else:
+			block += [progname]
+			block += format_usage_arguments(self.arguments, base_length)
+		return [block]
+
+	def automan_description(self):
+		ret = []
+		if self.help:
+			ret += parse_argparse_text(self.help)
+		ret += format_arguments(self.arguments) + format_subcommands(self.subcommands)
+		return ret
+
+
+class AutoMan(Directive):
+	required_arguments = 1
+	optional_arguments = 0
+	option_spec = dict(prog=unchanged_required, minimal=bool)
+	has_content = False
+
+	def run(self):
+		minimal = self.options.get('minimal')
+		module = self.arguments[0]
+		template_args = {}
+		template_args.update(get_authors())
+		get_argparser = __import__(str(module), fromlist=[str('get_argparser')]).get_argparser
+		parser = get_argparser(AutoManParser)
+		if minimal:
+			container = nodes.container()
+			container += parser.automan_usage(self.options['prog'])
+			container += parser.automan_description()
+			return [container]
+		synopsis_section = nodes.section(
+			'',
+			nodes.title(text='Synopsis'),
+			ids=['synopsis-section'],
+		)
+		synopsis_section += parser.automan_usage(self.options['prog'])
+		description_section = nodes.section(
+			'', nodes.title(text='Description'),
+			ids=['description-section'],
+		)
+		description_section += parser.automan_description()
+		author_section = nodes.section(
+			'', nodes.title(text='Author'),
+			nodes.paragraph(
+				'',
+				nodes.Text('Written by {authors} and contributors. The glyphs in the font patcher are created by {glyphs_author}.'.format(
+					**get_authors()
+				))
+			),
+			ids=['author-section']
+		)
+		issues_url = 'https://github.com/powerline/powerline/issues'
+		reporting_bugs_section = nodes.section(
+			'', nodes.title(text='Reporting bugs'),
+			nodes.paragraph(
+				'',
+				nodes.Text('Report {prog} bugs to '.format(
+					prog=self.options['prog'])),
+				nodes.reference(
+					issues_url, issues_url,
+					refuri=issues_url,
+					internal=False,
+				),
+				nodes.Text('.'),
+			),
+			ids=['reporting-bugs-section']
+		)
+		return [synopsis_section, description_section, author_section, reporting_bugs_section]
+
+
+def setup(app):
+	app.add_directive('automan', AutoMan)