Fix #2892: Added `-a (--append-syspath) option to sphinx-apidoc`

CHANGES

@@ -107,6 +107,7 @@ Features added
   apidoc is run frequently.
 * #2851: `sphinx.ext.math` emits missing-reference event if equation not found
 * #1210: ``eqref`` role now supports cross reference
+* #2892: Added ``-a`` (``--append-syspath``) option to `sphinx-apidoc`
 
 Bugs fixed
 ----------

doc/invocation.rst

@@ -458,6 +458,10 @@ The :program:`sphinx-apidoc` script has several options:
    This option makes sphinx-apidoc put module documentation before submodule
    documentation.
 
+.. option:: -a
+
+   Append module_path to sys.path.
+
 .. option:: -H project
 
    Sets the project name to put in generated files (see :confval:`project`).

doc/man/sphinx-apidoc.rst

@@ -49,6 +49,7 @@ Options
 
 These options are used with ``-F``:
 
+-a              Append module_path to sys.path.
 -H <project>    Project name to put into the configuration.
 -A <author>     Author name(s) to put into the configuration.
 -V <version>    Project version.

sphinx/apidoc.py

@@ -299,6 +299,9 @@ Note: By default this script will not overwrite already created files.""")
                       help='file suffix (default: rst)', default='rst')
     parser.add_option('-F', '--full', action='store_true', dest='full',
                       help='Generate a full project with sphinx-quickstart')
+    parser.add_option('-a', '--append-syspath', action='store_true',
+                      dest='append_syspath',
+                      help='Append module_path to sys.path, used when --full is given')
     parser.add_option('-H', '--doc-project', action='store', dest='header',
                       help='Project name (default: root module name)')
     parser.add_option('-A', '--doc-author', action='store', dest='author',
@@ -366,6 +369,8 @@ Note: By default this script will not overwrite already created files.""")
             mastertocmaxdepth = opts.maxdepth,
             mastertoctree = text,
             language = 'en',
+            module_path = rootpath,
+            append_syspath = opts.append_syspath,
         )
         if isinstance(opts.header, binary_type):
             d['project'] = d['project'].decode('utf-8')

sphinx/templates/quickstart/conf.py_t

@@ -19,9 +19,19 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+{% if append_syspath -%}
+import os
+import sys
+sys.path.insert(0, u'{{ module_path }}')
+{% else -%}
 # import os
 # import sys
+{% if module_path -%}
+# sys.path.insert(0, u'{{ module_path }}')
+{% else -%}
 # sys.path.insert(0, os.path.abspath('.'))
+{% endif -%}
+{% endif %}
 
 # -- General configuration ------------------------------------------------