Recommend additional workflow example for working with Jinja templates that requires -aE option

[SunbrightShinobi]

So the improvements made in reference to #34 did provide a fix to my issue but the example in the documentation at https://github.com/executablebooks/sphinx-autobuild#working-on-a-sphinx-html-theme didn't help with a cached environment like with multiple jinja files.

So I recommend adding an additional workflow example:

Working on a Sphinx Project with Jinja Templating
When working on a Sphinx project that contains Jinja Templating, it is required to disable Sphinx's incremental builds and to always fully rebuild and not use cached files bypassing the -aE option to sphinx-autobuild. Otherwise, the changes made to templates and configuration files used in templates will be seen and a rebuild will occur but only using the cached rst files, not new ones generated from the updated templates.

sphinx-autobuild -aE docs docs/_build/html --watch path/to/theme
This results in slower builds, but it ensures that all pages are built from the same state of the templates and configurations.

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[pradyunsg]

Hi @binarylandscapes! Thanks for filing this issue!

Could you clarify what you mean by "Sphinx project that contains Jinja Templating"? I'm not I follow what workflow this is recommendation is for -- is this a project containing _templates in the docs/ directory¹? Is this a custom theme based that's available locally on a different path?

¹I know that both of those are knobs that are configurable, but this conveys the question I'm asking, so... 🤷🏽‍♂️

[SunbrightShinobi]

Hello,

So this is separate from the HTML template updates.

This is basically pulling in restructeredtext templates into a rst file from a .jinja file and incorporating variables from yaml dictionaries and yes I use custom paths

1. So I have a custom folder at a project level for use in multiple docs that in the make file is soft-linked into /source for each document it contains images, jinja files, etc.
2. I then place these jinja templates in rst files as needed. Perfect example: I have detailed instructions for logging into windows with a certain username. I may do this 30x in the entire document in various rst files. I use jinja to put that template in each rst file and the same text is rendered into rst for the final output. If I need to edit then I only have to edit the jinja file and rebuild and all 30x instance are auto updated as well
3. The Jinja Extension during the build cycle will compile the jinja into the rst output for output render format
4. In the case of sphinx-autobuild without the -aE then after first built, if you only update the jinja file, it will rebuild recognizing the change in file but will not rebuild the rst file and only use the cached one
5. So in a similar use case to your example of someone testing HTML template changes and needing a non cached rebuild each time on a change, the same applies to my use case.

So what you have works its was just a suggestion of another example use case but unknown how many others use this method than me and previous coworkers but I have not created any special extensions to accomplish this, just integrated jinja2 with yaml and several others. I basically use this method to provide single sourced documentation steps with variable information for cookie cutter datacenters like large build out documents from baremetal hardware -> bios/firmware updates -> OS -> applications -> etc to very detailed levels.

Hopefully that answered your questions