Deprecation: templates now have an .html.jinja extension #162

Deprecation of .html templates in favor of .html.jinja templates

I will release a new version of mkdocstrings-python very soon, and this version will deprecate the .html suffix of Jinja templates in favor of a .html.jinja suffix. The reason is, this will improve editing experience for both the maintainers of handlers (which provide Jinja templates) and users of these handlers who override them with custom templates, by allowing automatic language detection and proper Jinja highlighting when working on templates.

To maintain backward compatibility, the .html files will still be supported, both when overriding them (your own template) and when extending them (with Jinja's {% extends "..." %} tag).

Transition

There will be two transition periods:

1. during the first transition period, users will see
   • INFO messages telling them that overriding <template>.html templates is deprecated, and that they should override <template>.html.jinja templates instead.
   • INFO messages telling them that extending _base/<template>.html is deprecated, and that they should extend _base/<template>.html.jinja instead.
   • WARNING messages telling them that overriding _base/<template>.html.jinja (or .html) is not supported, and that they should override <template>.html.jinja instead.
2. during the second transition period, both INFO messages above will become WARNING messages

Remember: WARNING messages will make your strict MkDocs builds fail! (mkdocs build -s)

I expect the first period to last a few months, and the second period to last at least as long, or maybe longer. After that, support for .html templates will be removed (.html templates will be silently unused and ignored).

Overriding base templates is not supported

Regarding the warning about overriding base templates: this was never intended to work, and therefore never supported. I'll make sure the docs are clear about this. The solution is easy: just move your templates one folder up, and delete the _base folder. Thankfully, I've identified very few projects overriding base templates, see https://github.com/search?q=path%3A*.html+path%3Apython%2Fmaterial%2F_base&type=Code&ref=advsearch.

Also note that our templates now use Jinja blocks, so you can customize only specific parts of them by extending the base templates instead of copy-pasting the whole base content:

{% extends "_base/class.html" %}

{% block docstring scoped %}
  ... custom docstring header
  {{ super() }}  {# reuse parent block's contents #}
  ... custom docstring footer
{% endblock docstring %}

(dummy example, just to show the syntax)

Testing

You can test these changes right now by installing mkdocstrings-python from the main branch. For Insiders users, install pawamoy-insiders/mkdocstrings-python from the upstream-changes branch. Serve your docs, check that everything is correct, then you can safely go back to installing latest PyPI version instead of main branch and rest assured that the upgrade won't break anything in your project. If you see something not working, please open a new issue!

Versions released as 1.10.1 and 1.10.1.1.8.2.

That is all! Thank you for your understanding 😄 Let me know here if you have any concerns or if anything is unclear 🙂