Open SunbrightShinobi opened 3 years ago
Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
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! :tada:
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/
directory1? Is this a custom theme based that's available locally on a different path?
1I know that both of those are knobs that are configurable, but this conveys the question I'm asking, so... 🤷🏽♂️
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
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
So the improvements made in reference to https://github.com/executablebooks/sphinx-autobuild/issues/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.