diff --git a/sphinxarg/ext.py b/sphinxarg/ext.py index 847a187..3a286c0 100644 --- a/sphinxarg/ext.py +++ b/sphinxarg/ext.py @@ -821,7 +821,22 @@ def run(self): domain = cast('ArgParseDomain', self.env.get_domain(ArgParseDomain.name)) domain.add_argparse_command(result, node_id, self.index_groups) - items.append(nodes.literal_block(text=result['usage'])) + fromfile_prefix = result.get('fromfile_prefix_chars', '') + + usage = result['usage'] + if fromfile_prefix: + usage += f' [{fromfile_prefix[0]}file]' + items.append(nodes.literal_block(text=usage)) + + if len(fromfile_prefix) > 1: + children = [nodes.Text('Additional arguments will be read from files passed as ')] + for i, p in enumerate(fromfile_prefix): + if i > 0: + children.append(nodes.Text(' or ')) + children.append(nodes.literal(text=f'{p}file')) + children.append(nodes.Text('.')) + items.append(nodes.paragraph('', '', *children)) + items.extend( self._print_action_groups( result, diff --git a/sphinxarg/parser.py b/sphinxarg/parser.py index dd18457..9a07f5a 100644 --- a/sphinxarg/parser.py +++ b/sphinxarg/parser.py @@ -76,6 +76,7 @@ def parse_parser(parser, data=None, **kwargs): } _try_add_parser_attribute(data, parser, 'description') _try_add_parser_attribute(data, parser, 'epilog') + _try_add_parser_attribute(data, parser, 'fromfile_prefix_chars') for action in parser._get_positional_actions(): if not isinstance(action, _SubParsersAction): continue diff --git a/test/sample-default-supressed.py b/test/sample-default-supressed.py index ab4a72d..25faf86 100644 --- a/test/sample-default-supressed.py +++ b/test/sample-default-supressed.py @@ -3,7 +3,9 @@ def get_parser(): parser = ArgumentParser( - prog='sample-default-suppressed', description='Test suppression of version default' + prog='sample-default-suppressed', + description='Test suppression of version default', + fromfile_prefix_chars='=@', ) parser.add_argument( '--version', help='print version number', action='version', version='1.2.3' diff --git a/test/sample-directive-special.py b/test/sample-directive-special.py index d7ff97f..2a4780e 100644 --- a/test/sample-directive-special.py +++ b/test/sample-directive-special.py @@ -5,6 +5,7 @@ def get_parser(): parser = argparse.ArgumentParser( prog='sample-directive-special', description='Support SphinxArgParse HTML testing (with defaults)', + fromfile_prefix_chars='@', ) parser.add_argument( diff --git a/test/test_default_html.py b/test/test_default_html.py index 27dc351..2beb2ff 100644 --- a/test/test_default_html.py +++ b/test/test_default_html.py @@ -60,6 +60,8 @@ ('.//section/dl/dd/p/code/span', '420'), ('.//section/dl/dd/p/code/span', "'*.rst"), ('.//section/dl/dd/p/code/span', r"\['\*.rst',"), + (".//div[@class='highlight']", r'\[@file\]'), + ('.//p', 'Additional arguments will be read from files', False), ], ), ( @@ -69,6 +71,11 @@ ('.//h1', 'Default suppressed'), ('.//h2', 'Named Arguments'), ('.//section/dl/dd/p', 'Default', False), + (".//div[@class='highlight']", r'\[=file\]'), + ( + './/p', + 'Additional arguments will be read from files passed as =file or @file.', + ), ], ), ], diff --git a/test/utils/xpath.py b/test/utils/xpath.py index e7f3ce4..1260bdc 100644 --- a/test/utils/xpath.py +++ b/test/utils/xpath.py @@ -1,5 +1,7 @@ import re +from lxml import etree as lxmletree + def check_xpath(etree, fname, path, check, be_found=True): nodes = list(etree.xpath(path)) @@ -16,12 +18,7 @@ def check_xpath(etree, fname, path, check, be_found=True): else: def get_text(node): - if node.text is not None: - # the node has only one text - return node.text - else: - # the node has tags and text; gather texts just under the node - return ''.join(n.tail or '' for n in node) + return lxmletree.tostring(node, encoding='unicode', method='text') rex = re.compile(check) if be_found: