From 0fff2f652c6456bb31e348aece87a989bb3ba40f Mon Sep 17 00:00:00 2001 From: Dean Malmgren Date: Sat, 9 Aug 2014 05:01:32 -0500 Subject: [PATCH] trying a totally different approach to displaying command line documentation. programoutput sux --- bin/textract | 32 ++++----------------------- docs/command_line_interface.rst | 27 +++++++++++++---------- docs/conf.py | 22 +------------------ docs/python_package.rst | 8 +++++++ requirements/python-dev | 2 +- textract/cli.py | 38 +++++++++++++++++++++++++++++++++ 6 files changed, 68 insertions(+), 61 deletions(-) create mode 100644 textract/cli.py diff --git a/bin/textract b/bin/textract index 53164bbf..ee6a3332 100755 --- a/bin/textract +++ b/bin/textract @@ -5,40 +5,16 @@ import sys import argparse -try: - import argcomplete -except ImportError: - pass +import argcomplete -from textract import VERSION +from textract.cli import get_parser from textract import process -from textract.colors import red from textract.exceptions import CommandLineError +from textract.colors import red -# command line options here -parser = argparse.ArgumentParser( - description='Command line tool for extracting text from any document' -) -parser.add_argument( - 'filename', help='Filename to extract text.', -).completer = argcomplete.completers.FilesCompleter -parser.add_argument( - '-o', '--output', type=argparse.FileType('w'), default='-', - help='output raw text in this file', -) -parser.add_argument( - '-m', '--method', default='', - help='specify a method of extraction for formats that support it', -) -parser.add_argument( - '-v', '--version', action='version', version='%(prog)s '+VERSION, -) - -# enable autocompletion with argcomplete -argcomplete.autocomplete(parser) - # extract text +parser = get_parser() args = parser.parse_args() try: output = process(**vars(args)) diff --git a/docs/command_line_interface.rst b/docs/command_line_interface.rst index c68c1846..560922d6 100644 --- a/docs/command_line_interface.rst +++ b/docs/command_line_interface.rst @@ -15,14 +15,19 @@ on any :ref:`supported file type `. Full documentation for the command line interface is available with the ``-h/--help`` command line option: -.. command-output:: textract -h - -To make the command line interface as usable as possible, -autocompletion of available options with textract is enabled by -@kislyuk's amazing `argcomplete -`_ package. Follow -instructions to `enable global autocomplete -`_ -and you should be all set. As an example, this is also configured in -the `virtual machine provisioning for this project -`_. +.. argparse:: + :module: textract.cli + :func: get_parser + :prog: textract + +.. note:: + + To make the command line interface as usable as possible, + autocompletion of available options with textract is enabled by + @kislyuk's amazing `argcomplete + `_ package. Follow + instructions to `enable global autocomplete + `_ + and you should be all set. As an example, this is also configured + in the `virtual machine provisioning for this project + `_. diff --git a/docs/conf.py b/docs/conf.py index e6e773e0..2ce31929 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,26 +22,6 @@ sys.path.insert(0, project_root) import textract -def insert_in_environ_list(VARIABLE, *values): - for value in values: - if os.environ.get(VARIABLE): - os.environ[VARIABLE] = ':'.join((value, os.environ[VARIABLE])) - else: - os.environ[VARIABLE] = value - -# manipulate the python path to properly display the output of -# textract -h in the command line documentation -insert_in_environ_list('PATH', os.path.join(project_root, 'bin')) - -# manipulate PYTHONPATH to correctly point to the virtualenv that is -# used on readthedocs (this is irrelevant in the development -# environment) -insert_in_environ_list( - 'PYTHONPATH', - project_root, - '/var/build/user_builds/textract/envs/latest/lib/python2.7/site-packages', -) - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -54,7 +34,7 @@ def insert_in_environ_list(VARIABLE, *values): 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.viewcode', - 'sphinxcontrib.programoutput', + 'sphinxarg.ext', ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/python_package.rst b/docs/python_package.rst index 07b39cdf..c9bc757d 100644 --- a/docs/python_package.rst +++ b/docs/python_package.rst @@ -131,6 +131,14 @@ textract.parsers.txt_parser module +textract.cli module +------------------- + +.. automodule:: textract.cli + :members: + :undoc-members: + :show-inheritance: + textract.exceptions module -------------------------- diff --git a/requirements/python-dev b/requirements/python-dev index 8d5d59cf..d74ddd8a 100644 --- a/requirements/python-dev +++ b/requirements/python-dev @@ -9,4 +9,4 @@ pep8 # for documentation sphinx sphinx_rtd_theme -sphinxcontrib-programoutput \ No newline at end of file +sphinx-argparse \ No newline at end of file diff --git a/textract/cli.py b/textract/cli.py new file mode 100644 index 00000000..1aebd5e6 --- /dev/null +++ b/textract/cli.py @@ -0,0 +1,38 @@ +import argparse + +import argcomplete + +from . import VERSION + + +# This function is necessary to enable autodocumentation of the script +# output +def get_parser(): + """Initialize the parser for the command line interface and bind the + autocompletion functionality""" + + # initialize the parser + parser = argparse.ArgumentParser( + description='Command line tool for extracting text from any document' + ) + + # define the command line options here + parser.add_argument( + 'filename', help='Filename to extract text.', + ).completer = argcomplete.completers.FilesCompleter + parser.add_argument( + '-o', '--output', type=argparse.FileType('w'), default='-', + help='output raw text in this file', + ) + parser.add_argument( + '-m', '--method', default='', + help='specify a method of extraction for formats that support it', + ) + parser.add_argument( + '-v', '--version', action='version', version='%(prog)s '+VERSION, + ) + + # enable autocompletion with argcomplete + argcomplete.autocomplete(parser) + + return parser