Make the doc argument optional; use the docstring for the caller's module by default

README.rst

@@ -110,13 +110,15 @@ API
 
 .. code:: python
 
-    docopt(doc, argv=None, help=True, version=None, options_first=False)
+    docopt(doc=None, argv=None, help=True, version=None, options_first=False)
 
-``docopt`` takes 1 required and 4 optional arguments:
+``docopt`` takes 5 optional arguments:
 
-- ``doc`` could be a module docstring (``__doc__``) or some other
-  string that contains a **help message** that will be parsed to
-  create the option parser.  The simple rules of how to write such a
+- ``doc`` is a string that contains a **help message** that will be
+  parsed to create the option parser.  By default the docstring for the
+  caller's module is used, which is equivalent to ``docopt(__doc__)``.
+
+  The simple rules of how to write such a
   help message are given in next sections.  Here is a quick example of
   such a string:
 

docopt.py

@@ -487,7 +487,7 @@ def __repr__(self):
         return '{%s}' % ',\n '.join('%r: %r' % i for i in sorted(self.items()))
 
 
-def docopt(doc, argv=None, help=True, version=None, options_first=False):
+def docopt(doc=None, argv=None, help=True, version=None, options_first=False):
     """Parse `argv` based on command-line interface described in `doc`.
 
     `docopt` creates your command-line interface based on its
@@ -498,7 +498,8 @@ def docopt(doc, argv=None, help=True, version=None, options_first=False):
     Parameters
     ----------
     doc : str
-        Description of your command-line interface.
+        Description of your command-line interface.  The docstring
+        for the caller's module is used if not provided.
     argv : list of str, optional
         Argument vector to be parsed. sys.argv[1:] is used if not
         provided.
@@ -550,6 +551,13 @@ def docopt(doc, argv=None, help=True, version=None, options_first=False):
       at https://github.com/docopt/docopt#readme
 
     """
+    if doc is None:
+        import inspect
+        frame = inspect.stack()[1][0]
+        doc = frame.f_globals['__doc__']
+        if doc is None:
+            raise ValueError("No module-level docstring found.  Either write one or provide a 'doc' argument.")
+
     argv = sys.argv[1:] if argv is None else argv
 
     usage_sections = parse_section('usage:', doc)

test_docopt.py

@@ -389,6 +389,16 @@ def test_allow_double_dash():
 
 
 def test_docopt():
+    with raises(ValueError):
+        docopt()
+
+    global __doc__
+    __doc__ = '''Usage: prog [-v] A
+
+             Options: -v  Be verbose.'''
+    assert docopt(argv='arg') == {'-v': False, 'A': 'arg'}
+    assert docopt(argv='-v arg') == {'-v': True, 'A': 'arg'}
+
     doc = '''Usage: prog [-v] A
 
              Options: -v  Be verbose.'''