Can't get local templates to work

[JamesALeedham]

I want to customize the way classes are templated.

So I copied https://raw.githubusercontent.com/readthedocs/sphinx-autoapi/master/autoapi/templates/python/class.rst to a source/_autoapi_templates folder, saving it as class.rst. Then in source/conf.py I set autoapi_template_dir = '_autoapi_templates'.

When I run make html, however, my template changes aren't reflected in class output. What's going wrong?

[AWhetter]

Do you have an example project where this isn't working?

[JamesALeedham]

Thanks very much for getting back to me. Just to say that sphinx-autoapi looks really good so far, so much easier to understand than either sphinx-apidoc or sphinx.ext.autosummary. I look forward to getting it in production on Readthedocs asap.

Please find attached a tar.gz with a sample project. I'm running Ubuntu 18.04 and a Python 3.7.5 virtual env. Running pip freeze reports:

alabaster==0.7.12
astroid==2.3.3
Babel==2.8.0
certifi==2020.4.5.1
chardet==3.0.4
docutils==0.16
idna==2.9
imagesize==1.2.0
Jinja2==2.11.2
lazy-object-proxy==1.4.3
MarkupSafe==1.1.1
packaging==20.3
pkg-resources==0.0.0
Pygments==2.6.1
pyparsing==2.4.7
pytz==2019.3
PyYAML==5.3.1
requests==2.23.0
six==1.14.0
snowballstemmer==2.0.0
Sphinx==3.0.2
sphinx-autoapi==1.3.0
sphinx-rtd-theme==0.4.3
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4
typed-ast==1.4.1
Unidecode==1.1.1
urllib3==1.25.9
wrapt==1.11.2

To set up the project, I ran:

1. pip install sphinx sphinx-autoapi sphinx_rtd_theme
2. make html

In source/_autoapi_templates/class.rst I made some (nonsense) local edits to the class template. This is referenced in source/conf.py using autoapi_template_dir = '_autoapi_templates'.

My expectation was that the presence of the local class.rst file would override site-packages/autoapi/templates/python/class.rst. However, this doesn't seem to be the case - the nonsense edits don't show up in the built html.

TEST.tar.gz

[Markus-Goetz]

I can confirm the behaviour @JamesALeedham experiences. Together with a colleague, we closely followed the guide on your tutorial web pages. We were unable to use a custom template as described. However, changes to the template in the site-packages folder affected the building.

Per environment: we have tested it for sphinx-autoapi version 1.2.0 as well as 1.3.0 in a virtual environment created using python -m venv ...

[mesca]

In conf.py:

templates_path = ['_templates']
autoapi_template_dir = '_templates/autoapi'

And move your template to: _templates/autoapi/python/class.rst

[JamesALeedham]

Brilliant! Thanks @mesca ! That works...

So it seems the (mandatory) bit I was missing was a /python/ directory in the local template path. Perhaps this doc could be made a bit more explicit...

[Markus-Goetz]

Same here. Thanks for the quick response. Definitely upvoting the doc change.

[AWhetter]

Thanks for the suggestions. I've included an explained example in the documentation to make this more clear.