Before this change, target_uris would be generated as `index.html#foo`.
This makes it difficult to rename the generated document and can require reloading the document when following a link.
After this change, they are just `#foo`, which avoids the above problems.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This normalizes the description of the configuration value so that its default value's unit is the same as the internal one (i.e., seconds).
This PR improves the logic for detecting and eliminating ANSI color codes and other escape sequences introduced by Sphinx. ANSI escape sequences that are not natively known to Sphinx are not eliminated (e.g., VT100-specific functions).
As a user and/or extension developer, it can be a source of confusion when,
on performing a `sphinx-build` for a cached project,
an unchanged configuration variable is always marked as changed (triggering a full rebuild).
This is often due to the variable being an unpicklable value,
which is silently omitted from the cache (i.e. the `environment.pickle`).
This commit introduces a specific warning for when a configuration variable is omitted from the cache,
allowing users to understand the root of the problem.
The key issue this commit seeks to address, is that existing tools / documentation often lead users to mistakenly use object types and not role names, a classic example being `function` not `func`
Previously, the warning message for using e.g. `` external:function`target` `` (with `py` as the default domain), would be:
```
WARNING: role for external cross-reference not found: function
```
This gives no information to the user on how to fix the issue, even though there is actually quite an easy fix
This commit adds logic to create more specific / helpful warning messages, e.g.
```
WARNING: role for external cross-reference not found in domains 'py', 'std': 'function' (perhaps you meant one of: 'py:func', 'py:obj')
```
This goes through the same original logic but, if the role is not found, it will look if the role name is actually an available object type on the domain(s), and then suggest its related roles.
This commit also reverts #12133, which provided a (silent) fallback to auto convert an object type to a role name.
