search

sphinx-contrib / sphinxcontrib-towncrier

An RST directive for injecting a Towncrier-generated changelog draft containing fragments for the unreleased (next) project version. Demo: https://ansible-pylibssh.rtfd.io/changelog. Docs: https://sphinxcontrib-towncrier.rtfd.io
https://pypi.org/p/sphinxcontrib-towncrier
BSD 3-Clause "New" or "Revised" License
18 stars 18 forks source link

📝 Rebuild any documents using the directive #23

Closed webknjaz closed 4 years ago

webknjaz commented 4 years ago

This change addresses #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:

webknjaz commented 4 years ago

@ewjoachim mind taking a rough look? It's a workaround-ish thingy that addresses #1 in a non-granular way. I think I'll implement a better solution as a part of #8 sometime later, once I figure out how to make it right...

ewjoachim commented 4 years ago

I'm off for a week, sorry :) Feel free to move on, I'll review later, even post-merge.

webknjaz commented 4 years ago

@ewjoachim ah, sure :) Have a great vacation! It's just a one-liner, though. I just wanted to make sure you see the current motivation.