Why do the tag index pages use toctree?

[HeinischValentin]

Hi,

I want to use this extension in one of my documentation projects, however I came across some issues. One of them is the usage of a toctree on the generated index pages.

All documents are included in some toctree in the project. Including them a second time inside the index page, breaks some things. I noticed this issue together with the sphinx-rtd-theme, because navigating from the index page to the page where the tag is being used expands the sidebar in the (imo) wrong location. The sidebar expands under the index chapter and not under the chapter the target document is included in.

I would assume, that there are more issues that come with including the same document twice in the same project. This comment from a Sphinx maintainer also emphasizes the issue: https://github.com/sphinx-doc/sphinx/issues/5145#issuecomment-403513547

I think it could be an improvement to exchange the toctree for a list of references, but maybe I am missing some feature of the toctree here.

Edit: With "index page" I am referencing to the autogenerated index page, showing all occurrences of one tag across the project, and not the root_doc "index.rst" page.

[JWCook]

The sidebar expands under the index chapter and not under the chapter the target document is included in.

I've noticed this too, although I think the sidebar behavior depends somewhat on the Sphinx theme in use.

Options would be:

• Use a list of references by default, and/or
• Produce the tag index pages from a jinja template that users could modify if needed

A simple template using references instead of a toctree would look something like:

.. _sphx_tag_{{ ref_label }}:

{{ tags_page_title ~ ': ' ~ tag_name | underline }}

{{ tags_page_header }}

{% for path in tag_page_paths %}
* :doc:`../{{ path }}`
{%- endfor %}

Context variables passed from a Tag instance to that template would look like:

context = {
    'tags_page_title': app.config.tags_page_title,
    'tags_page_header': app.config.tags_page_header,
    'tag_name': self.name,
    'ref_label': self.file_basename,
    'tag_page_paths': sorted([i.relpath(srcdir) for i in items]),
}

What do you think, @melissawm @story645 ? I'd be willing to do that after #101 is done.

[melissawm]

That sounds reasonable and more flexible thab a toctree, I agree. Would be great!

I had some personal issues come up but hope I'll get a chance to finish my PR soon.