From 0d95377bbfa76e10d0ece26ba77e15125b05bae0 Mon Sep 17 00:00:00 2001 From: Ashley Whetter Date: Sun, 5 Apr 2020 18:50:32 -0700 Subject: [PATCH] Accept template directory relative to conf.py Closes #184 --- CHANGELOG.rst | 2 ++ autoapi/extension.py | 15 ++++++++++++--- docs/how_to.rst | 3 ++- docs/reference/config.rst | 8 +++++++- docs/tutorials.rst | 8 ++++---- 5 files changed, 27 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 6c67bd7..31504bb 100644 --- a/CHANGELOG.rst +++ b/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) diff --git a/autoapi/extension.py b/autoapi/extension.py index 998cce2..4cf17b6 100644 --- a/autoapi/extension.py +++ b/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( - app, template_dir=app.config.autoapi_template_dir, url_root=url_root - ) + template_dir = app.config.autoapi_template_dir + 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: diff --git a/docs/how_to.rst b/docs/how_to.rst index bcea833..9635595 100644 --- a/docs/how_to.rst +++ b/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 diff --git a/docs/reference/config.rst b/docs/reference/config.rst index 5b2b113..0d0c0fa 100644 --- a/docs/reference/config.rst +++ b/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 `_ @@ -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. diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 32de79e..5bc0e1a 100644 --- a/docs/tutorials.rst +++ b/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::