diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py
index 30bef6674..11f1861d8 100644
--- a/sphinx/cmdline.py
+++ b/sphinx/cmdline.py
@@ -83,11 +83,27 @@ def handle_exception(app, args, exception, stderr=sys.stderr):
file=stderr)
-def main(argv=sys.argv[1:]): # type: ignore
- # type: (List[unicode]) -> int
+def get_parser():
+ # type: () -> argparse.ArgumentParser
parser = argparse.ArgumentParser(
- usage='usage: %(prog)s [OPTIONS] SOURCEDIR OUTDIR [FILENAMES...]',
- epilog='For more information, visit .')
+ usage='usage: %(prog)s [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]',
+ epilog='For more information, visit .',
+ description="""
+Generate documentation from source files.
+
+sphinx-build generates documentation from the files in SOURCEDIR and places it
+in OUTPUTDIR. It looks for 'conf.py' in SOURCEDIR for the configuration
+settings. The 'sphinx-quickstart' tool may be used to generate template files,
+including 'conf.py'
+
+sphinx-build can create documentation in different formats. A format is
+selected by specifying the builder name on the command line; it defaults to
+HTML. Builders can also perform other tasks related to documentation
+processing.
+
+By default, everything that is outdated is built. Output only for selected
+files can be built by specifying individual filenames.
+""")
parser.add_argument('--version', action='version', dest='show_version',
version='%%(prog)s %s' % __display_version__)
@@ -112,7 +128,7 @@ def main(argv=sys.argv[1:]): # type: ignore
'all files')
group.add_argument('-d', metavar='PATH', dest='doctreedir',
help='path for the cached environment and doctree '
- 'files (default: outdir/.doctrees)')
+ 'files (default: OUTPUTDIR/.doctrees)')
group.add_argument('-j', metavar='N', default=1, type=int, dest='jobs',
help='build in parallel with N processes where '
'possible')
@@ -120,7 +136,7 @@ def main(argv=sys.argv[1:]): # type: ignore
group = parser.add_argument_group('build configuration options')
group.add_argument('-c', metavar='PATH', dest='confdir',
help='path where configuration file (conf.py) is '
- 'located (default: same as sourcedir)')
+ 'located (default: same as SOURCEDIR)')
group.add_argument('-C', action='store_true', dest='noconfig',
help='use no config file at all, only -D options')
group.add_argument('-D', metavar='setting=value', action='append',
@@ -159,6 +175,13 @@ def main(argv=sys.argv[1:]): # type: ignore
group.add_argument('-P', action='store_true', dest='pdb',
help='run Pdb on exception')
+ return parser
+
+
+def main(argv=sys.argv[1:]): # type: ignore
+ # type: (List[unicode]) -> int
+
+ parser = get_parser()
# parse options
try:
args = parser.parse_args(argv)