The first time sphinx-build is run on Windows, it issues a warning like
some\path\index.rst:1: WARNING: 'any' reference target not found: ../_tags/development
and does not generate any of the tag index pages (e.g. _tags/xyz). On a subsequent run of sphinx-build, it then does generate these index pages, but because the original file containing the tag hasn't changed, the tag badge on that page isn't turned into a link.
This can be demonstrated using the docs site and running the command sphinx-build -M html . _build -v.
First invocation:
Running Sphinx v7.2.6
making output directory... done
locale_dir R:\ray\src\sphinx-tags\docs\locales\en\LC_MESSAGES does not exist
Tags updated
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
The default value for `navigation_with_keys` will change to `False` in the next release. If you wish to preserve the old behavior for your site, set `navigation_with_keys=True` in the `html_theme_options` dict in your `conf.py` file. Be aware that `navigation_with_keys = True` has negative accessibility implications: https://github.com/pydata/pydata-sphinx-theme/issues/1492
locale_dir R:\ray\src\sphinx-tags\docs\locales\en\LC_MESSAGES does not exist
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 15 source files that are out of date
updating environment: locale_dir R:\ray\src\sphinx-tags\docs\locales\en\LC_MESSAGES does not exist
[new config] 8 added, 0 changed, 0 removed
reading sources... [ 12%] _tags/tagsindex
reading sources... [ 25%] configuration
reading sources... [ 38%] contribute/index
reading sources... [ 50%] examples/examples
reading sources... [ 62%] examples/index
reading sources... [ 75%] examples/raw-cells
reading sources... [ 88%] index
reading sources... [100%] quickstart
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [ 12%] _tags/tagsindex
writing output... [ 25%] configuration
writing output... [ 38%] contribute/index
writing output... [ 50%] examples/examples
writing output... [ 62%] examples/index
writing output... [ 75%] examples/raw-cells
writing output... [ 88%] index
writing output... [100%] quickstart
R:\ray\src\sphinx-tags\docs\contribute\index.rst:1: WARNING: 'any' reference target not found: ../_tags/development
R:\ray\src\sphinx-tags\docs\examples\examples.md:5: WARNING: 'any' reference target not found: ../_tags/md-examples
R:\ray\src\sphinx-tags\docs\examples\examples.md:5: WARNING: 'any' reference target not found: ../_tags/tag-documentation
R:\ray\src\sphinx-tags\docs\examples\examples.md:5: WARNING: 'any' reference target not found: ../_tags/tags-with-emojis-check
R:\ray\src\sphinx-tags\docs\examples\raw-cells.ipynb:10: WARNING: 'any' reference target not found: ../_tags/notebooks
R:\ray\src\sphinx-tags\docs\examples\raw-cells.ipynb:10: WARNING: 'any' reference target not found: ../_tags/celltags
R:\ray\src\sphinx-tags\docs\quickstart.rst:6: WARNING: 'any' reference target not found: _tags/tag-documentation
R:\ray\src\sphinx-tags\docs\quickstart.rst:6: WARNING: 'any' reference target not found: _tags/tag-installation
generating indices... genindex done
copying linked files...
copying notebooks ... [100%] examples/raw-cells.ipynb
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 8 warnings.
The HTML pages are in _build\html.
Second invocation:
Running Sphinx v7.2.6
loading pickled environment... done
Tags updated
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
The default value for `navigation_with_keys` will change to `False` in the next release. If you wish to preserve the old behavior for your site, set `navigation_with_keys=True` in the `html_theme_options` dict in your `conf.py` file. Be aware that `navigation_with_keys = True` has negative accessibility implications: https://github.com/pydata/pydata-sphinx-theme/issues/1492
locale_dir R:\ray\src\sphinx-tags\docs\locales\en\LC_MESSAGES does not exist
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: locale_dir R:\ray\src\sphinx-tags\docs\locales\en\LC_MESSAGES does not exist
7 added, 1 changed, 0 removed
reading sources... [ 12%] _tags/celltags
reading sources... [ 25%] _tags/development
reading sources... [ 38%] _tags/md-examples
reading sources... [ 50%] _tags/notebooks
reading sources... [ 62%] _tags/tag-documentation
reading sources... [ 75%] _tags/tag-installation
reading sources... [ 88%] _tags/tags-with-emojis-check
reading sources... [100%] _tags/tagsindex
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [ 11%] _tags/celltags
writing output... [ 22%] _tags/development
writing output... [ 33%] _tags/md-examples
writing output... [ 44%] _tags/notebooks
writing output... [ 56%] _tags/tag-documentation
writing output... [ 67%] _tags/tag-installation
writing output... [ 78%] _tags/tags-with-emojis-check
writing output... [ 89%] _tags/tagsindex
writing output... [100%] index
generating indices... genindex done
copying linked files...
copying notebooks ...
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in _build\html.
I've tried this on macOS using the same versions of Sphinx (7.2.6), Myst (2.0.0) and Python (3.11) and am not seeing the same issue. I'm not sure if there are any other package versions that would matter.
Based on using git bisect, this issue appears to have been introduced by commit 5c56b6e1bbfec.
The first time
sphinx-buildis run on Windows, it issues a warning likeand does not generate any of the tag index pages (e.g.
_tags/xyz). On a subsequent run ofsphinx-build, it then does generate these index pages, but because the original file containing the tag hasn't changed, the tag badge on that page isn't turned into a link.This can be demonstrated using the
docssite and running the commandsphinx-build -M html . _build -v.First invocation:
Second invocation:
I've tried this on macOS using the same versions of Sphinx (7.2.6), Myst (2.0.0) and Python (3.11) and am not seeing the same issue. I'm not sure if there are any other package versions that would matter.
Based on using
git bisect, this issue appears to have been introduced by commit 5c56b6e1bbfec.