Allow disabling default substitutions in the config

[webknjaz]

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 like setuptools-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 and version to static values, but that's not desired.

Additional context

• possibly related discussion: Request of implementation: global substitutions #2173
• definition in the source code: https://github.com/sphinx-doc/sphinx/blob/f85f50e/sphinx/transforms/__init__.py#L37-L42
• Fix |release| RST substitution in docs having incomplete values for development versions pytest-dev/pytest#12538

cc @RonnyPfannschmidt

[picnixz]

Mmh. That's something I can understand and would be willing to fix. Let's see where it should be done.

Some solutions:

• add a configuration value to indicate which substitutions to disable.

• 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.

[webknjaz]

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.

[webknjaz]

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.

[picnixz]

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.

[webknjaz]

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.