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

5 files changed, 21 insertions, 0 deletions

diff --git a/CHANGES b/CHANGES
index 25f662a85..7a0d880ba 100644
--- a/CHANGES
+++ b/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
 ----------
diff --git a/doc/invocation.rst b/doc/invocation.rst
index ce51fe080..6e9a25606 100644
--- a/doc/invocation.rst
+++ b/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`).
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
index a01d2a82f..be0c3d3a3 100644
--- a/doc/man/sphinx-apidoc.rst
+++ b/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.
diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py
index 72ecd1c69..216ed353f 100644
--- a/sphinx/apidoc.py
+++ b/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')
diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t
index 5022bbdb5..ee5858b21 100644
--- a/sphinx/templates/quickstart/conf.py_t
+++ b/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 ------------------------------------------------