Skip to content

Referencing indices from navigation doesn't work #11135

Open
@Paebbels

Description

@Paebbels

Describe the bug

When referencing indices from navigation bar (toctree), it's working for builtin indices like modindex, but not for user defined indices.

How to Reproduce

Take the recipe example from Sphinx documentation and add this to your toctree:

.. toctree::

   Ingredients <ingredient>
   Ingredients <recipe-ingredient>

Environment Information

Sphinx: 5.3
Builder: HTML

Sphinx extensions

No response

Additional context

In general I like the new feature of allowing toctree entries to reference indices by symbolic name. For many years I needed to do a workaround for this by adding dummy pages (genindex.rst), which got overwritten by the real HTML pages.

But, I see two mistakes in the current implementation:

  1. indices are referenced by there simple name and not there fully-qualified name. In toctree you write modindex, but not py-modindex. This causes several problems:
    • In :ref: role, the same page is referenced with py-modindex, but in toctree not.
    • If an extension also writes a module index called modindex, there is an overlap in names, despite the Python module index is located in it's own domain. This could also be any other index name overlapping between two domain extensions.
  2. User defined indices can't be referenced in toctree, but builtin indices can.
    • But, user defined indices can be referenced by :ref: role using the FQN: recipe-ingredient.

Expected bahavior:

  1. toctree should reference the Python module index with py-modindex.
  2. User defined indices should be usage in toctree too.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions