trying a totally different approach to displaying command line docume…

…ntation. programoutput sux

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))

docs/command_line_interface.rst

@@ -15,14 +15,19 @@ on any :ref:`supported file type <supporting>`. 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
-<https://github.com/kislyuk/argcomplete>`_ package.  Follow
-instructions to `enable global autocomplete
-<https://github.com/kislyuk/argcomplete#activating-global-completion>`_
-and you should be all set. As an example, this is also configured in
-the `virtual machine provisioning for this project
-<http://github.com/deanmalmgren/textract/blob/master/provision/development.sh#L17>`_. 
+.. 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
+    <https://github.com/kislyuk/argcomplete>`_ package.  Follow
+    instructions to `enable global autocomplete
+    <https://github.com/kislyuk/argcomplete#activating-global-completion>`_
+    and you should be all set. As an example, this is also configured
+    in the `virtual machine provisioning for this project
+    <http://github.com/deanmalmgren/textract/blob/master/provision/development.sh#L17>`_.

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.

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
 --------------------------
 

requirements/python-dev

@@ -9,4 +9,4 @@ pep8
 # for documentation
 sphinx
 sphinx_rtd_theme
-sphinxcontrib-programoutput
+sphinx-argparse

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