Support ArgumentParser.fromfile_prefix_chars

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,

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

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'

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(

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.',
+                ),
             ],
         ),
     ],

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: