support reading Argparse instances inside classes

So far, shphinxarg only has support for reading/importing Argparse
instances from global variables/attributes within a module.  However,
there are use cases where Argparse is used inside classes of a module,
not as a global variable.  This is particularly the case for uses
of 'argparse' in the context of CLI / REPL style user interfaces,
such as for example those built using the 'cmd2' module.

This change introduces the ability to specify a path in ':func:'
using the '.'-notation (e.g. 'PysimApp.bulk_script_parser').

Initial patch by: Harald Welte <laforge@osmocom.org>
Co-authored by: Vadim Yanitskiy <fixeria@osmocom.org>

sphinxarg/ext.py

@@ -486,6 +486,28 @@ def _open_filename(self):
         # raise exception
         raise FileNotFoundError(self.options['filename'])
 
+    def _get_parser(self, obj, path):
+        for attr in path.split('.'):
+            try:
+                if isinstance(obj, dict):
+                    obj = obj[attr]
+                else:
+                    obj = getattr(obj, attr)
+            except (KeyError, AttributeError) as exc:
+                msg = (
+                    f'"{obj}" has no key/attribute "{attr} (path: {path})"\n'
+                    f'Incorrect argparse :module: or :func: values?'
+                )
+                raise self.error(msg) from exc
+        if isinstance(obj, ArgumentParser):
+            parser = obj
+        elif 'passparser' in self.options:
+            parser = ArgumentParser()
+            obj(parser)
+        else:
+            parser = obj()
+        return parser
+
     def run(self):
         if 'module' in self.options and 'func' in self.options:
             module_name = self.options['module']
@@ -501,7 +523,7 @@ def run(self):
             exec(code, mod)
             module_name = None
             attr_name = self.options['func']
-            func = mod[attr_name]
+            parser = self._get_parser(mod, attr_name)
         else:
             msg = ':module: and :func: should be specified, or :ref:, or :filename: and :func:'
             raise self.error(msg)
@@ -517,22 +539,8 @@ def run(self):
                         f'{sys.exc_info()[1]}'
                     )
                     raise self.error(msg) from exc
+                parser = self._get_parser(mod, attr_name)
 
-                if not hasattr(mod, attr_name):
-                    msg = (
-                        f'Module "{module_name}" has no attribute "{attr_name}"\n'
-                        f'Incorrect argparse :module: or :func: values?'
-                    )
-                    raise self.error(msg)
-                func = getattr(mod, attr_name)
-
-        if isinstance(func, ArgumentParser):
-            parser = func
-        elif 'passparser' in self.options:
-            parser = ArgumentParser()
-            func(parser)
-        else:
-            parser = func()
         if 'path' not in self.options:
             self.options['path'] = ''
         path = str(self.options['path'])

test/roots/test-default-html/inside-class.rst

@@ -0,0 +1,15 @@
+Argparse inside class Foo
+#########################
+
+.. argparse::
+   :filename: test/sample-inside-class.py
+   :prog: sample-inside-class-foo
+   :func: Foo.parser
+
+Argparse inside class Foo.Bar
+#############################
+
+.. argparse::
+   :filename: test/sample-inside-class.py
+   :prog: sample-inside-class-foo-bar
+   :func: Foo.Bar.parser

test/sample-inside-class.py

@@ -0,0 +1,17 @@
+import argparse
+
+
+desc = 'Test parsing of Argparse instances inside classes'
+
+class Foo:
+    parser = argparse.ArgumentParser(prog=f'{__name__}-foo',
+                                     description=desc)
+    parser.add_argument('--foo-arg1', help='foo-arg1 help')
+    parser.add_argument('--foo-arg2', help='foo-arg2 help')
+
+
+    class Bar:
+        parser = argparse.ArgumentParser(prog=f'{__name__}-foo-bar',
+                                         description=desc)
+        parser.add_argument('--foo-bar-arg1', help='foo-bar-arg1 help')
+        parser.add_argument('--foo-bar-arg2', help='foo-bar-arg2 help')

test/test_default_html.py

@@ -98,6 +98,22 @@ def get_text(node):
                 ('.//section/dl/dd/p', 'Default', False),
             ],
         ),
+        (
+            'inside-class.html',
+            [
+                (".//section[@id='argparse-inside-class-foo']/h1", 'Argparse inside class Foo'),
+                (".//section[@id='argparse-inside-class-foo']//div[@class='highlight']//span", 'usage'),
+                (".//section[@id='Foo.parser-named-arguments']/h2", 'Named Arguments'),
+                (".//section[@id='Foo.parser-named-arguments']/dl/dt[1]/kbd", '--foo-arg1'),
+                (".//section[@id='Foo.parser-named-arguments']/dl/dt[2]/kbd", '--foo-arg2'),
+
+                (".//section[@id='argparse-inside-class-foo-bar']/h1", 'Argparse inside class Foo.Bar'),
+                (".//section[@id='argparse-inside-class-foo-bar']//div[@class='highlight']//span", 'usage'),
+                (".//section[@id='Foo.Bar.parser-named-arguments']/h2", 'Named Arguments'),
+                (".//section[@id='Foo.Bar.parser-named-arguments']/dl/dt[1]/kbd", '--foo-bar-arg1'),
+                (".//section[@id='Foo.Bar.parser-named-arguments']/dl/dt[2]/kbd", '--foo-bar-arg2'),
+            ],
+        ),
     ],
 )
 @pytest.mark.sphinx('html', testroot='default-html')