Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
SunbrightShinobi opened this issue Dec 22, 2020 · 2 comments

Comments

@SunbrightShinobi
Copy link

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.

@pradyunsg
Copy link
Collaborator

pradyunsg commented Feb 6, 2021

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... 🤷🏽‍♂️

@SunbrightShinobi
Copy link
Author

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

@sphinx-doc sphinx-doc deleted a comment from welcome bot Oct 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants