Fixed failure to build out of source conf.py files

Closes #293

Author: AWhetter

CHANGELOG.rst

@@ -115,6 +115,10 @@ Bug Fixes
   Fixed an unnecessary deprecation warning being raised when running
   sphinx-build from the same directory as conf.py.
 * Fixed properties documented by Autodoc directives geting documented as methods.
+* `#293 <https://github.com/readthedocs/sphinx-autoapi/issues/293>`:
+  Fixed failure to build out of source conf.py files.
+  Configuration values using relative values are now relative to the source directory
+  instead of relative to the conf.py file.
 
 
 V1.5.1 (2020-10-01)

autoapi/extension.py

@@ -55,7 +55,7 @@ class RemovedInAutoAPI2Warning(DeprecationWarning):
     warnings.filterwarnings("default", category=RemovedInAutoAPI2Warning)
 
 
-def _normalise_autoapi_dirs(autoapi_dirs, confdir):
+def _normalise_autoapi_dirs(autoapi_dirs, srcdir):
     normalised_dirs = []
 
     if isinstance(autoapi_dirs, str):
@@ -64,7 +64,7 @@ def _normalise_autoapi_dirs(autoapi_dirs, confdir):
         if os.path.isabs(path):
             normalised_dirs.append(path)
         else:
-            normalised_dirs.append(os.path.normpath(os.path.join(confdir, path)))
+            normalised_dirs.append(os.path.normpath(os.path.join(srcdir, path)))
 
     return normalised_dirs
 
@@ -96,7 +96,7 @@ def run_autoapi(app):  # pylint: disable=too-many-branches
             app.config.autoapi_options.append("show-module-summary")
 
     # Make sure the paths are full
-    normalised_dirs = _normalise_autoapi_dirs(app.config.autoapi_dirs, app.confdir)
+    normalised_dirs = _normalise_autoapi_dirs(app.config.autoapi_dirs, app.srcdir)
     for _dir in normalised_dirs:
         if not os.path.exists(_dir):
             raise ExtensionError(
@@ -133,11 +133,11 @@ def run_autoapi(app):  # pylint: disable=too-many-branches
     template_dir = app.config.autoapi_template_dir
     if template_dir and not os.path.isabs(template_dir):
         if not os.path.isdir(template_dir):
-            template_dir = os.path.join(app.confdir, app.config.autoapi_template_dir)
-        elif app.confdir != os.getcwd():
+            template_dir = os.path.join(app.srcdir, app.config.autoapi_template_dir)
+        elif app.srcdir != os.getcwd():
             warnings.warn(
                 "autoapi_template_dir will be expected to be "
-                " relative to conf.py instead of "
+                "relative to the Sphinx source directory instead of "
                 "relative to where sphinx-build is run\n",
                 RemovedInAutoAPI2Warning,
             )
@@ -173,7 +173,7 @@ def run_autoapi(app):  # pylint: disable=too-many-branches
 def build_finished(app, exception):
     if not app.config.autoapi_keep_files and app.config.autoapi_generate_api_docs:
         normalized_root = os.path.normpath(
-            os.path.join(app.confdir, app.config.autoapi_root)
+            os.path.join(app.srcdir, app.config.autoapi_root)
         )
         if app.verbosity > 1:
             LOGGER.info(bold("[AutoAPI] ") + darkgreen("Cleaning generated .rst files"))

docs/how_to.rst

@@ -13,8 +13,8 @@ Simply copy whichever templates you want to customise to a local directory
 and edit them.
 To get AutoAPI to use these templates,
 point the :confval:`autoapi_template_dir` configuration option to your directory.
-It can be absolute, or relative to the root of the documentation directory
-(ie the directory with the ``conf.py`` file).
+It can be absolute, or relative to the root of the documentation source directory
+(ie the directory passed to ``sphinx-build``).
 
 .. code-block:: python
 
@@ -67,7 +67,7 @@ How to Configure Where Documentation Appears in the TOC Tree
 
 The :confval:`autoapi_root` configuration option defines where generated documentation is output.
 To change where documentation is output,
-simply change this option to another directory relative to the ``conf.py`` file:
+simply change this option to another directory relative to the documentation source directory:
 
 .. code-block:: python
 

docs/reference/config.rst

@@ -7,8 +7,7 @@ Configuration Options
 
    Paths (relative or absolute) to the source code that you wish to generate your API documentation from.
    The paths are searched recursively for files matching :confval:`autoapi_file_patterns`.
-   Relative paths should be relative to the root of the documentation directory
-   (ie the directory with the ``conf.py`` file).
+   Relative paths should be relative to the source directory of your documentation.
 
    For Python, if a package directory is specified,
    the package directory itself will be included in the relative path of the children.
@@ -37,8 +36,7 @@ Configuration Options
 
    A directory that has user-defined templates to override our default templates.
    The path can either be absolute,
-   or relative to the root of the documentation directory
-   (ie the directory with the ``conf.py`` file).
+   or relative to the source directory of your documentation files.
    An path relative to where `sphinx-build` is run
    is allowed for backwards compatibility only
    and will be removed in a future version.
@@ -137,8 +135,7 @@ Customisation Options
 
    Path to output the generated AutoAPI files into,
    including the generated index page.
-   This path must be relative to the root of the documentation directory
-   (ie the directory with the ``conf.py`` file).
+   This path must be relative to the source directory of your documentation files.
    This can be used to place the generated documentation
    anywhere in your documentation hierarchy.
 

docs/tutorials.rst

@@ -39,7 +39,8 @@ we need to add it to the list of extensions in Sphinx's ``conf.py`` file::
 For Python, there is only one required configuration option that we need to set.
 :confval:`autoapi_dirs` tells AutoAPI which directories contain
 the source code to document.
-This can either be absolute, or relative to Sphinx's conf.py file.
+These can either be absolute, or relative to the source directory of
+your documentation files.
 For example, say we have a package and we have used ``sphinx-quickstart``
 to create a Sphinx project in a ``docs/`` folder.
 The directory structure might look like this:
@@ -131,7 +132,8 @@ For Go, this is::
 
 The second configuration option is :confval:`autoapi_dirs`,
 which tells AutoAPI which directories contain the source code to document.
-These can either be absolute, or relative to Sphinx's `conf.py` file.
+These can either be absolute, or relative to the source directory of
+your documentation files.
 So if your documentation was inside a ``docs/`` directory
 and your source code is in an ``example`` directory one level up,
 you would configure :confval:`autoapi_dirs` to be::
@@ -167,7 +169,8 @@ For Javascript, this is::
 
 The second configuration option is :confval:`autoapi_dirs`,
 which tells AutoAPI which directories contain the source code to document.
-These can either be absolute, or relative to Sphinx's `conf.py` file.
+These can either be absolute, or relative to the source directory of
+your documentation files.
 So if your documentation was inside a ``docs/`` directory
 and your source code is in an ``example`` directory one level up,
 you would configure :confval:`autoapi_dirs` to be::
@@ -196,7 +199,7 @@ By default, ``docfx`` will output metadata files into the ``_api`` path.
 You can configure which path to output files into by setting the path in your
 `docfx configuration file <https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#3-docfx-json-format>`_
 in your project repository.
-For example, if your ``conf.py`` file is located inside a ``docs/`` directory:
+For example, if your documentation source files are located inside a ``docs/`` directory:
 
 .. code:: json
 
@@ -223,7 +226,8 @@ For .NET, this is::
 
 The second configuration option is :confval:`autoapi_dirs`,
 which tells AutoAPI which directories contain the source code to document.
-These can either be absolute, or relative to Sphinx's `conf.py` file.
+These can either be absolute, or relative to the source directory of
+your documentation files.
 So if your documentation was inside a ``docs/`` directory
 and your source code is in an ``example`` directory one level up,
 you would configure :confval:`autoapi_dirs` to be::

tests/python/pymovedconfpy/confpy/conf.py

@@ -0,0 +1 @@
+../../pyexample/conf.py

tests/python/pymovedconfpy/example

@@ -0,0 +1 @@
+../pyexample/example

tests/python/pymovedconfpy/index.rst

@@ -0,0 +1 @@
+../pyexample/index.rst

tests/python/pymovedconfpy/manualapi.rst

@@ -0,0 +1 @@
+../pyexample/manualapi.rst

tests/python/test_pyintegration.py

@@ -19,10 +19,10 @@
 )
 
 
-def rebuild(confoverrides=None, **kwargs):
+def rebuild(confoverrides=None, confdir=".", **kwargs):
     app = Sphinx(
         srcdir=".",
-        confdir=".",
+        confdir=confdir,
         outdir="_build/text",
         doctreedir="_build/.doctrees",
         buildername="text",
@@ -121,6 +121,17 @@ def test_show_inheritance(self, builder):
         assert "Bases:" in example_file
 
 
+class TestMovedConfPy(TestSimpleModule):
+    @pytest.fixture(autouse=True, scope="class")
+    def built(self, builder):
+        builder(
+            "pymovedconfpy",
+            confdir="confpy",
+            warningiserror=True,
+            confoverrides={"suppress_warnings": ["app"]},
+        )
+
+
 class TestSimpleStubModule:
     @pytest.fixture(autouse=True, scope="class")
     def built(self, builder):