Accept template directory relative to conf.py

Closes #184

CHANGELOG.rst

@@ -66,6 +66,8 @@ Bug Fixes
 * (Python) autoapifunction directive no longer documents async functions as
   a normal function.
 * (Python) Fixed unicode decode errors in some Python 3 situations.
+* Documentation more accurately describes what configuration accepts
+  relative paths and where they are relative to.
 
 
 v1.1.0 (2019-06-23)

autoapi/extension.py

@@ -124,9 +124,18 @@ def run_autoapi(app):  # pylint: disable=too-many-branches
         )
 
     sphinx_mapper = LANGUAGE_MAPPERS[app.config.autoapi_type]
-    sphinx_mapper_obj = sphinx_mapper(
+    template_dir = app.config.autoapi_template_dir
-        app, template_dir=app.config.autoapi_template_dir, url_root=url_root
+    if template_dir:
-    )
+        if not os.path.isdir(template_dir):
+            template_dir = os.path.join(app.confdir, app.config.autoapi_template_dir)
+        elif not os.path.isabs(template_dir):
+            warnings.warn(
+                "autoapi_template_dir will be expected to be "
+                " relative to conf.py instead of "
+                "relative to where sphinx-build is run\n",
+                RemovedInAutoAPI2Warning,
+            )
+    sphinx_mapper_obj = sphinx_mapper(app, template_dir=template_dir, url_root=url_root)
     app.env.autoapi_mapper = sphinx_mapper_obj
 
     if app.config.autoapi_file_patterns:

docs/how_to.rst

@@ -13,7 +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 where ``sphinx-build`` is run.
+It can be absolute, or relative to the root of the documentation directory
+(ie the directory with the ``conf.py`` file).
 
 .. code-block:: python
 

docs/reference/config.rst

@@ -33,6 +33,12 @@ Configuration Options
 	Default: ``''``
 
 	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).
+	An path relative to where `sphinx-build` is run
+	is allowed for backwards compatibility only
+	and will be removed in a future version.
 
 	You can view the default templates in the
 	`autoapi/templates <https://github.com/readthedocs/sphinx-autoapi/tree/master/autoapi/templates>`_
@@ -109,7 +115,7 @@ Customisation Options
 
 	Path to output the generated AutoAPI files into,
 	including the generated index page.
-	This path should be relative to the root of the documentation directory
+	This path must be relative to the root of the documentation directory
 	(ie the directory with the ``conf.py`` file).
 	This can be used to place the generated documentation
 	anywhere in your documentation hierarchy.

docs/tutorials.rst

@@ -39,7 +39,7 @@ 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.
-These can either be absolute, or relative to where you run Sphinx.
+This can either be absolute, or relative to Sphinx's conf.py file.
 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 +131,7 @@ 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 where you run Sphinx.
+These can either be absolute, or relative to Sphinx's `conf.py` file.
 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 +167,7 @@ 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 where you run Sphinx.
+These can either be absolute, or relative to Sphinx's `conf.py` file.
 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::
@@ -223,7 +223,7 @@ 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 where you run Sphinx.
+These can either be absolute, or relative to Sphinx's `conf.py` file.
 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::