Implement fragment-dependent cache invalidation in Sphinx for RST documents using the extension #1
Comments
|
Note: if anyone finds a smart idea for this, I'll definitely steal it in https://github.com/peopledoc/sphinx-github-changelog and vice versa. (and I'm convinced there's a technical way of handling this, not just reminding the user to make the job of the computer :) ) |
|
We should be calling this on all the rst files in the fragment folder. |
|
@ewjoachim interesting... But how would sphinx know that this is connected to a directive in a certain file? I thought we need to point it to the document that uses the directive. |
|
No, this is done in the directive code itself, so Sphinx knows where it is. |
|
Fact is we could have multiple directives, each pointing to a different towncrier config and this would still work in theory |
|
Nice! Although, the current implementation has one global setting for the towncrier config and I don't think that one project would need more (unless it's a monorepo, I guess, but then the docs would likely be separate anyway). P.S. The main Towncrier CLI only supports custom config in their repo master, not in the released version so it's all only theoretical atm. |
webknjaz
changed the title
This solution is suboptimal because it forces Sphinx to rebuild the document regardless of whether the news fragments have changed in any way. OTOH, using `BuildEnvironment.note_dependency()` would be rather useless in `TowncrierDraftEntriesDirective.run()` since it'd only make it depend on the existing fragment changes (that almost never happens) and would ignore any new fragments appearing on disk (because the only dependencies declared would be the ones that existed at the time of the first directive run). The next step would be implementing tracking of the fragments outside of the directive using 'env-get-outdated' combined with tracking of the documents that use the directive via `BuildEnvironment` custom attribute and `EnvironmentCollector` for the Sphinx parallel mode support. Refs: * sphinx-contrib#1 * sphinx-contrib#1 * sphinx-doc/sphinx#8040
This change addresses sphinx-contrib#1 only partially and as such it needs a follow-up. The solution is suboptimal because it forces Sphinx to rebuild documents regardless of whether the news fragments have changed in any way. OTOH, using `BuildEnvironment.note_dependency()` would be rather useless in `TowncrierDraftEntriesDirective.run()` since it'd only make it depend on the existing fragment changes (that almost never happens) and would ignore any new fragments appearing on disk (because the only dependencies declared would be the ones that existed at the time of the first directive run). The next step would be implementing tracking of the fragments outside of the directive using 'env-get-outdated' combined with tracking of the documents that use the directive via `BuildEnvironment` custom attribute and `EnvironmentCollector` for the Sphinx parallel mode support. Refs: * sphinx-contrib#1 * sphinx-doc/sphinx#8040
|
FTR the approach with |
This change adds a minimal workaround for #1 that results in the documents using the directive will be always rebuilt unconditionally.
webknjaz
changed the title
To speed-up sequential builds, Sphinx caches documents as doctrees. This cache is based on whether the tracked RST files have changed and does not know anything about the changes in the directive output.
So including this directive into the document may result in it not picking up the new change fragments.
We need to explicitly document this and add some pointers on how to force rebuilds.
This idea is coming from ansible/pylibssh#120 as reported by @ewjoachim.
The text was updated successfully, but these errors were encountered: