This is an automated email from the git hooks/post-receive script. tbooth-guest pushed a commit to branch master in repository sphinxcontrib-autoprogram.
commit 04a93a6e2c4130de6fc5b7ad3e1d71c3a0e41075 Author: Tim Booth <[email protected]> Date: Sat Jan 31 15:41:46 2015 +0000 Imported Upstream version 0.1.1 --- MANIFEST.in | 3 + PKG-INFO | 37 ++++ README.rst | 11 + setup.cfg | 11 + setup.py | 57 +++++ sphinxcontrib/__init__.py | 13 ++ sphinxcontrib/autoprogram.py | 234 +++++++++++++++++++++ sphinxcontrib_autoprogram.egg-info/PKG-INFO | 37 ++++ sphinxcontrib_autoprogram.egg-info/SOURCES.txt | 13 ++ .../dependency_links.txt | 1 + .../namespace_packages.txt | 1 + sphinxcontrib_autoprogram.egg-info/not-zip-safe | 1 + sphinxcontrib_autoprogram.egg-info/requires.txt | 1 + sphinxcontrib_autoprogram.egg-info/top_level.txt | 1 + 14 files changed, 421 insertions(+) diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..45dd5f5 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,3 @@ +include README +include LICENSE +include CHANGES.* diff --git a/PKG-INFO b/PKG-INFO new file mode 100644 index 0000000..3729d4c --- /dev/null +++ b/PKG-INFO @@ -0,0 +1,37 @@ +Metadata-Version: 1.1 +Name: sphinxcontrib-autoprogram +Version: 0.1.1 +Summary: Documenting CLI programs +Home-page: https://bitbucket.org/birkenfeld/sphinx-contrib +Author: Hong Minhee +Author-email: [email protected] +License: BSD +Description: ``sphinxcontrib.autoprogram`` --- Documenting CLI programs + ========================================================== + + This contrib extension, ``sphinxcontrib.autoprogram``, provides an automated + way to document CLI programs. It scans ``arparser.ArgumentParser`` object, + and then expands it into a set of ``.. program::`` and ``.. option::`` + directives. + + You can find the documentation from the following URL: + + https://pythonhosted.org/sphinxcontrib-autoprogram/ + +Platform: any +Classifier: Development Status :: 4 - Beta +Classifier: Environment :: Console +Classifier: Environment :: Web Environment +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Operating System :: OS Independent +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 2.6 +Classifier: Programming Language :: Python :: 2.7 +Classifier: Programming Language :: Python :: 3.3 +Classifier: Programming Language :: Python :: Implementation :: CPython +Classifier: Programming Language :: Python :: Implementation :: PyPy +Classifier: Programming Language :: Python :: Implementation :: Stackless +Classifier: Topic :: Documentation +Classifier: Topic :: Software Development :: Documentation +Classifier: Topic :: Utilities diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..e3bd953 --- /dev/null +++ b/README.rst @@ -0,0 +1,11 @@ +``sphinxcontrib.autoprogram`` --- Documenting CLI programs +========================================================== + +This contrib extension, ``sphinxcontrib.autoprogram``, provides an automated +way to document CLI programs. It scans ``arparser.ArgumentParser`` object, +and then expands it into a set of ``.. program::`` and ``.. option::`` +directives. + +You can find the documentation from the following URL: + +https://pythonhosted.org/sphinxcontrib-autoprogram/ diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..f21bbe0 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,11 @@ +[egg_info] +tag_build = +tag_date = 0 +tag_svn_revision = 0 + +[bdist_wheel] +universal = 1 + +[aliases] +release = egg_info -RDb '' + diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..2bb92ca --- /dev/null +++ b/setup.py @@ -0,0 +1,57 @@ +# -*- coding: utf-8 -*- +from __future__ import with_statement + +import sys + +from setuptools import setup, find_packages + + +# Do not change the variable name. It's parsed by doc/conf.py script. +version = '0.1.1' + +requires = ['Sphinx >= 1.2'] + +if sys.version_info < (2, 7): + requires.append('argparse') + + +def readme(): + with open('README.rst') as f: + return f.read() + + +setup( + name='sphinxcontrib-autoprogram', + version=version, + url='https://bitbucket.org/birkenfeld/sphinx-contrib', + license='BSD', + author='Hong Minhee', + author_email='minhee' '@' 'dahlia.kr', + description='Documenting CLI programs', + long_description=readme(), + zip_safe=False, + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Environment :: Web Environment', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: BSD License', + 'Operating System :: OS Independent', + 'Programming Language :: Python', + 'Programming Language :: Python :: 2.6', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 3.3', + 'Programming Language :: Python :: Implementation :: CPython', + 'Programming Language :: Python :: Implementation :: PyPy', + 'Programming Language :: Python :: Implementation :: Stackless', + 'Topic :: Documentation', + 'Topic :: Software Development :: Documentation', + 'Topic :: Utilities' + ], + platforms='any', + packages=find_packages(), + namespace_packages=['sphinxcontrib'], + include_package_data=True, + test_suite='sphinxcontrib.autoprogram.suite', + install_requires=requires +) diff --git a/sphinxcontrib/__init__.py b/sphinxcontrib/__init__.py new file mode 100644 index 0000000..ce7beff --- /dev/null +++ b/sphinxcontrib/__init__.py @@ -0,0 +1,13 @@ +# -*- coding: utf-8 -*- +""" + sphinxcontrib + ~~~~~~~~~~~~~ + + This package is a namespace package that contains all extensions + distributed in the ``sphinx-contrib`` distribution. + + :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +__import__('pkg_resources').declare_namespace(__name__) diff --git a/sphinxcontrib/autoprogram.py b/sphinxcontrib/autoprogram.py new file mode 100644 index 0000000..a427f9a --- /dev/null +++ b/sphinxcontrib/autoprogram.py @@ -0,0 +1,234 @@ +""" + sphinxcontrib.autoprogram + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + Documenting CLI programs. + + :copyright: Copyright 2014 by Hong Minhee + :license: BSD, see LICENSE for details. + +""" +import argparse +import collections +try: + import builtins +except ImportError: + import __builtin__ as builtins +import functools +import re +import unittest + +from docutils import nodes +from docutils.parsers.rst.directives import unchanged +from docutils.statemachine import ViewList +from sphinx.util.compat import Directive +from sphinx.util.nodes import nested_parse_with_titles +from sphinx.domains import std + +__all__ = ('BOOLEAN_OPTIONS', 'AutoprogramDirective', 'ScannerTestCase', + 'import_object', 'scan_programs', 'setup', 'suite') + + +def scan_programs(parser, command=[]): + options = [] + for arg in parser._actions: + if not (arg.option_strings or + isinstance(arg, argparse._SubParsersAction)): + name = (arg.metavar or arg.dest).lower() + desc = (arg.help or '') % {'default': arg.default} + options.append(([name], desc)) + for arg in parser._actions: + if arg.option_strings: + if isinstance(arg, (argparse._StoreAction, + argparse._AppendAction)): + metavar = (arg.metavar or arg.dest).lower() + names = ['{0} <{1}>'.format(option_string, metavar) + for option_string in arg.option_strings] + else: + names = list(arg.option_strings) + desc = (arg.help or '') % {'default': arg.default} + options.append((names, desc)) + yield command, options, parser.description or '' + if parser._subparsers: + choices = parser._subparsers._actions[-1].choices.items() + if not (hasattr(collections, 'OrderedDict') and + isinstance(choices, collections.OrderedDict)): + choices = sorted(choices, key=lambda pair: pair[0]) + for cmd, sub in choices: + if isinstance(sub, argparse.ArgumentParser): + for program in scan_programs(sub, command + [cmd]): + yield program + + +def import_object(import_name): + module_name, expr = import_name.split(':', 1) + mod = __import__(module_name) + reduce_ = getattr(functools, 'reduce', None) or reduce + mod = reduce_(getattr, module_name.split('.')[1:], mod) + globals_ = builtins + if not isinstance(globals_, dict): + globals_ = globals_.__dict__ + return eval(expr, globals_, mod.__dict__) + + +class AutoprogramDirective(Directive): + + has_content = False + required_arguments = 1 + option_spec = {'prog': unchanged} + + def make_rst(self): + import_name, = self.arguments + parser = import_object(import_name or '__undefined__') + prog = self.options.get('prog', parser.prog) + for commands, options, desc in scan_programs(parser): + command = ' '.join(commands) + title = '{0} {1}'.format(prog, command).rstrip() + yield '' + yield '.. program:: ' + title + yield '' + yield title + yield ('!' if commands else '?') * len(title) + yield '' + yield desc + yield '' + for option_strings, help_ in options: + yield '.. option:: {0}'.format(', '.join(option_strings)) + yield '' + yield ' ' + help_.replace('\n', ' \n') + yield '' + + def run(self): + node = nodes.section() + node.document = self.state.document + result = ViewList() + for line in self.make_rst(): + result.append(line, '<autoprogram>') + nested_parse_with_titles(self.state, result, node) + return node.children + + +def patch_option_role_to_allow_argument_form(): + """Before Sphinx 1.2.2, :rst:dir:`.. option::` directive hadn't + allowed to not start with a dash or slash, so it hadn't been possible + to represent positional arguments (not options). + + https://bitbucket.org/birkenfeld/sphinx/issue/1357/ + + It monkeypatches the :rst:dir:`.. option::` directive's behavior. + + """ + std.option_desc_re = re.compile(r'((?:/|-|--)?[-_a-zA-Z0-9]+)(\s*.*)') + + +def setup(app): + app.add_directive('autoprogram', AutoprogramDirective) + patch_option_role_to_allow_argument_form() + + +class ScannerTestCase(unittest.TestCase): + + def test_simple_parser(self): + parser = argparse.ArgumentParser(description='Process some integers.') + parser.add_argument('integers', metavar='N', type=int, nargs='*', + help='an integer for the accumulator') + parser.add_argument('-i', '--identity', type=int, default=0, + help='the default result for no arguments ' + '(default: 0)') + parser.add_argument('--sum', dest='accumulate', action='store_const', + const=sum, default=max, + help='sum the integers (default: find the max)') + programs = scan_programs(parser) + programs = list(programs) + self.assertEqual(1, len(programs)) + pair, = programs + program, options, desc = pair + self.assertEqual([], program) + self.assertEqual('Process some integers.', desc) + self.assertEqual(4, len(options)) + self.assertEqual( + (['n'], 'an integer for the accumulator'), + options[0] + ) + self.assertEqual( + (['-h', '--help'], 'show this help message and exit'), + options[1] + ) + self.assertEqual( + (['-i <identity>', '--identity <identity>'], + 'the default result for no arguments (default: 0)'), + options[2] + ) + self.assertEqual( + (['--sum'], 'sum the integers (default: find the max)'), + options[3] + ) + + def test_subcommands(self): + parser = argparse.ArgumentParser(description='Process some integers.') + subparsers = parser.add_subparsers() + max_parser = subparsers.add_parser('max', description='Find the max.') + max_parser.set_defaults(accumulate=max) + max_parser.add_argument('integers', metavar='N', type=int, nargs='+', + help='An integer for the accumulator.') + sum_parser = subparsers.add_parser('sum', + description='Sum the integers.') + sum_parser.set_defaults(accumulate=sum) + sum_parser.add_argument('integers', metavar='N', type=int, nargs='+', + help='An integer for the accumulator.') + programs = scan_programs(parser) + programs = list(programs) + self.assertEqual(3, len(programs)) + # main + program, options, desc = programs[0] + self.assertEqual([], program) + self.assertEqual('Process some integers.', desc) + self.assertEqual(1, len(options)) + self.assertEqual( + (['-h', '--help'], + 'show this help message and exit'), + options[0] + ) + # max + program, options, desc = programs[1] + self.assertEqual(['max'], program) + self.assertEqual('Find the max.', desc) + self.assertEqual(2, len(options)) + self.assertEqual((['n'], 'An integer for the accumulator.'), + options[0]) + self.assertEqual( + (['-h', '--help'], + 'show this help message and exit'), + options[1] + ) + # sum + program, options, desc = programs[2] + self.assertEqual(['sum'], program) + self.assertEqual('Sum the integers.', desc) + self.assertEqual(2, len(options)) + self.assertEqual((['n'], 'An integer for the accumulator.'), + options[0]) + + +class UtilTestCase(unittest.TestCase): + + def test_import_object(self): + cls = import_object('sphinxcontrib.autoprogram:UtilTestCase') + self.assertTrue(cls is UtilTestCase) + instance = import_object( + 'sphinxcontrib.autoprogram:UtilTestCase("test_import_object")' + ) + self.assertIsInstance(instance, UtilTestCase) + + if not hasattr(unittest.TestCase, 'assertIsInstance'): + def assertIsInstance(self, instance, cls): + self.assertTrue(isinstance(instance, cls), + '{0!r} is not an instance of {1.__module__}.' + '{1.__name__}'.format(instance, cls)) + + +suite = unittest.TestSuite() +suite.addTests( + unittest.defaultTestLoader.loadTestsFromTestCase(ScannerTestCase) +) +suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(UtilTestCase)) diff --git a/sphinxcontrib_autoprogram.egg-info/PKG-INFO b/sphinxcontrib_autoprogram.egg-info/PKG-INFO new file mode 100644 index 0000000..3729d4c --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/PKG-INFO @@ -0,0 +1,37 @@ +Metadata-Version: 1.1 +Name: sphinxcontrib-autoprogram +Version: 0.1.1 +Summary: Documenting CLI programs +Home-page: https://bitbucket.org/birkenfeld/sphinx-contrib +Author: Hong Minhee +Author-email: [email protected] +License: BSD +Description: ``sphinxcontrib.autoprogram`` --- Documenting CLI programs + ========================================================== + + This contrib extension, ``sphinxcontrib.autoprogram``, provides an automated + way to document CLI programs. It scans ``arparser.ArgumentParser`` object, + and then expands it into a set of ``.. program::`` and ``.. option::`` + directives. + + You can find the documentation from the following URL: + + https://pythonhosted.org/sphinxcontrib-autoprogram/ + +Platform: any +Classifier: Development Status :: 4 - Beta +Classifier: Environment :: Console +Classifier: Environment :: Web Environment +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: BSD License +Classifier: Operating System :: OS Independent +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 2.6 +Classifier: Programming Language :: Python :: 2.7 +Classifier: Programming Language :: Python :: 3.3 +Classifier: Programming Language :: Python :: Implementation :: CPython +Classifier: Programming Language :: Python :: Implementation :: PyPy +Classifier: Programming Language :: Python :: Implementation :: Stackless +Classifier: Topic :: Documentation +Classifier: Topic :: Software Development :: Documentation +Classifier: Topic :: Utilities diff --git a/sphinxcontrib_autoprogram.egg-info/SOURCES.txt b/sphinxcontrib_autoprogram.egg-info/SOURCES.txt new file mode 100644 index 0000000..ca1e696 --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/SOURCES.txt @@ -0,0 +1,13 @@ +MANIFEST.in +README.rst +setup.cfg +setup.py +sphinxcontrib/__init__.py +sphinxcontrib/autoprogram.py +sphinxcontrib_autoprogram.egg-info/PKG-INFO +sphinxcontrib_autoprogram.egg-info/SOURCES.txt +sphinxcontrib_autoprogram.egg-info/dependency_links.txt +sphinxcontrib_autoprogram.egg-info/namespace_packages.txt +sphinxcontrib_autoprogram.egg-info/not-zip-safe +sphinxcontrib_autoprogram.egg-info/requires.txt +sphinxcontrib_autoprogram.egg-info/top_level.txt \ No newline at end of file diff --git a/sphinxcontrib_autoprogram.egg-info/dependency_links.txt b/sphinxcontrib_autoprogram.egg-info/dependency_links.txt new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/dependency_links.txt @@ -0,0 +1 @@ + diff --git a/sphinxcontrib_autoprogram.egg-info/namespace_packages.txt b/sphinxcontrib_autoprogram.egg-info/namespace_packages.txt new file mode 100644 index 0000000..aa75604 --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/namespace_packages.txt @@ -0,0 +1 @@ +sphinxcontrib diff --git a/sphinxcontrib_autoprogram.egg-info/not-zip-safe b/sphinxcontrib_autoprogram.egg-info/not-zip-safe new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/not-zip-safe @@ -0,0 +1 @@ + diff --git a/sphinxcontrib_autoprogram.egg-info/requires.txt b/sphinxcontrib_autoprogram.egg-info/requires.txt new file mode 100644 index 0000000..ad30718 --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/requires.txt @@ -0,0 +1 @@ +Sphinx >= 1.2 \ No newline at end of file diff --git a/sphinxcontrib_autoprogram.egg-info/top_level.txt b/sphinxcontrib_autoprogram.egg-info/top_level.txt new file mode 100644 index 0000000..aa75604 --- /dev/null +++ b/sphinxcontrib_autoprogram.egg-info/top_level.txt @@ -0,0 +1 @@ +sphinxcontrib -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-med/sphinxcontrib-autoprogram.git _______________________________________________ debian-med-commit mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/debian-med-commit
