Running app.builder.build_update() During env-updated

[umamibeef]

Overview

I am finally finding the time to put together this question after many months away from the problem, so I apologize in advance if some details are missing. I am currently writing a custom extension to process custom directives which have tags associated with them that get their own pages which link to sections in the documents where the tags are references. I used https://github.com/melissawm/sphinx-tags as a big inspiration for this.

Problem

In the https://github.com/melissawm/sphinx-tags project implementation, tag summary files are generated prior the build starting, specifically in a builder-inited callback. This means that the generated files are picked up by the builder and everything is rendered without protest. This requires that the source files be pre-processed in order to look for the special directive fields, look for their list of tags, and generate files accordingly.

My custom directive's tags exist as multi-line option field of a larger directive, and the formatting and indentation of the directive is variable. I am hesitant to write a pre-processing parser for this because this is obtained "for free" during the main build loop. In addition to avoiding pre-proprocessing what is already being processed, I want to avoid the complexity associated with some of the features mentioned above (i.e. indentation level).

Current Workaround

My current workaround is to have two build phases, with another phase triggered right after env-updated through a app.builder.build_update() call, with a flag preventing it from being executed more than once. This successfully kicks off another build phase which in turn picks up on the generated files in my project. The downside, however, is that the writing portion of the build is triggered twice. On large documents, this adds a lot of time, and with certain writers (e.g. Atlassian Confluence Builder) this causes some bugger outputs due to it appending some data twice. Regardless of these quirks, this implementation is doing exactly what I need it to do, albeit a bit slower.

Questions and Final Thoughts

Is it possible for me to do a app.builder.build_update() call during an env-updated event, but at the same time prevent two output writing phases to occur? Is there a better way for me to accomplish what I'm trying to do here? If you've made it this far, thank you so much for your time. Looking forward to some new ideas and constructive criticisms!