`genindex` et al. inclusion in `toctree` directive results in a warning with the `latexpdf` builder

[BrunoMSantos]

Describe the bug

Adding genindex (or any other special docname) works perfectly with the html builder, but, despite producing the expected output for the latexpdf builder, it always warns:

WARNING: toctree contains ref to nonexisting file 'genindex' [toc.not_readable]

Possibly an unrelated issue, I then tried this with no change, which means the only directive somehow works differently when it guards a toctree directive or maybe its block is still evaluated before being discarded.

.. only:: html
   .. toctree::
      :hidden:

      genindex

Either way I see no way of cleanly suppressing the warning, which is annoying since I wanted to compile with -W.

How to Reproduce

$ cat index.rst .. toctree::

genindex $ cat conf.py $ sphinx-build -M html . html/ # this is fine $ sphinx-build -M latexpdf . pdf/ # this is not fine

Environment Information

Platform:              linux; (Linux-6.15.6-arch1-1-x86_64-with-glibc2.41)
Python version:        3.13.5 (main, Jun 21 2025, 09:35:00) [GCC 15.1.1 20250425])
Python implementation: CPython
Sphinx version:        8.2.3
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

Additional context

No response

[jfbu]

This is not an answer, but a comment that there should be no need to explicitly include genindex in a toctree. Actually, prior to #12500 the sphinx-quickstart produced a default index.rst including a :ref:`genindex` mark-up (but this was in an Indices and Tables section potentially producing redundancy in output, depending on the HTML theme).

It turns out that Sphinx default theme, Alabaster, does not include in the sidebars any link to the general index. The file genindex.html does exist in the HTML output but there is nowhere a link to it to be found.

In contrast, the "classic" theme sets the output pages to include an "index" link in footers and headers, next to the "next" (sic) or "previous" links.

Is the inclusion of genindex in a toctree in your project related to the above observation? If you want to get the output so show links to genindex.html with Alabaster theme some workaround is indeed needed.

[BrunoMSantos]

Interesting... And yeah, the only reason I added it to the index was that it wasn't there by default, though I usually use the theme furo, falling back to the default if not available.

Still, my understanding of the documentation still is that adding those entries to the toctree should work.

[jfbu]

Le 21 juil. 2025 à 14:48, Bruno Santos @.***> a écrit :

BrunoMSantos left a comment (sphinx-doc/sphinx#13733) https://github.com/sphinx-doc/sphinx/issues/13733#issuecomment-3096639897 Interesting... And yeah, the only reason I added it to the index was that it wasn't there by default, though I usually use the theme furo, falling back to the default if not available.

You can check the file genindex.html will be there in output also with theme furo, even without adding genindex to the toctree.

The proper way to "fix" missing links is to add to the html templates being used by the theme. The other day I asked an AI how to do that with alabaster theme... and the proposed way looked ok.

Still, my understanding of the documentation still is that adding those entries to the toctree should work.

Perhaps the documentation should be improved. Which part made you infer that genindex should be added to the toctree directive arguments ?

Fwiw, a warning is reported with other builders : singlehtml, man, texinfo. This is not only with the latex builder.

[BrunoMSantos]

Perhaps the documentation should be improved. Which part made you infer that genindex should be added to the toctree directive arguments ?

Well, with this added context, one can argue that I read too much into it, but

1. The file itself has always been generated as far as I know. Previously I used a :ref: to force it to be linked in.
2. Then, serendipitously, I stumbled on this change log containing a 'feature added' #10673: Make toctree accept ‘genindex’, ‘modindex’ and ‘search’ docnames. No subsequent entry suggests that this has been deprecated that I can find.
3. The index is not added by default in html like it is in LaTeX. In fact I had thought it wouldn't be added in LaTeX either until I looked into the warning.
4. Adding it in toctree does not yield any warning for the html builder and the toctree directive documentation simply lists these as special files not to be created and not not to be linked.

I'll probably tune the theme once I pick this up again, but that currently feels like a hack even having learned that some themes do / did link it by default in the past.

[jfbu]

Certainly you are right that #10673 makes your expectation fully legit! I was not aware of it, and as the latex, man, singlehtml and texinfo raise warnings in such circumstances, it appears #10673 overlooked such potential issue.

cc @brechtm, @AA-Turner.