Open webknjaz opened 1 week ago
Mmh. That's something I can understand and would be willing to fix. Let's see where it should be done.
Some solutions:
expose the default substitutions as a configuration value ; users that want to disable them could do something in their conf.py
like:
default_substitutions = [] # <- this would redefine all default substitutions
default_substitutions_custom = [...] # to include to the set of default ones
default_substitutions_ignore = [...] # to exclude from the set of default ones
Would it make sense? or do you have a better alternative? the first suggestion is just to add default_substitutions_ignore
, not the other configuration values.
I think the second variant is more flexible. However, custom
and ignore
are very confusing and generic. I'd use _include
and _exclude
suffixes as this pattern already exists in other tools. Other prefixes/suffixes I saw in the wild are extend-
/ _also
.
Thinking about this more, it would be useful to have some sort of document map, allowing us to define certain substitutions in some documents but not others. The use-case would be to have |release|
available in the document displaying a changelog with dynamically generated future changes preview.
Another thought: is it possible to auto-inject substitutions based on whether they're being referenced in RST? That should be possible to determine/modify in source-read
.
it possible to auto-inject substitutions based on whether they're being referenced in RST?
When you say "reference in RST", I assume that you meant if they are used with something like |x|
. The answer is yes, you can do it by using the .. replace
directive and put them in rst_prolog
configuration value. I personally think it's an overkill in general because this prolog would be added to every RST document which, when using autodoc, may be numerous!
I like the per-file substitution idea but I'm not sure about its interaction with includes for instance.
Alright, any improvement in the area is good. I won't be able to look into it this week. So I'll let you judge what's the best course of action.
Is your feature request related to a problem? Please describe.
When setting things like
release
to dynamically-generated versions like the ones produced from Git via tools likesetuptools-scm
, this results in cache invalidation on every single build, effectively rendering it unusable.Describe the solution you'd like
Projects that don't make use of substitutions like
|release|
/|version|
in their RST files, should be able to disable those so they don't influence the cache and let it be reused.Describe alternatives you've considered
Setting
release
andversion
to static values, but that's not desired.Additional context
cc @RonnyPfannschmidt