Broken links in version picker menu for HtmlDir index pages

[medmunds]

Details

• Read the Docs project URL: https://anymail.readthedocs.io/

In Sphinx-HtmlDir docs, the version picker menu has broken links on any page that is generated from a subdir/index.rst. The URLs for such pages look like .../subdir/, but the version picker menu incorrectly links to .../subdir/index/, which is a 404.

(Fairly certain this used to work correctly.)

Expected Result

To reproduce:

1. Go to (e.g.) https://anymail.readthedocs.io/en/stable/sending/. (This is a Sphinx-HtmlDir project, the source for this page is docs/sending/index.rst.)
2. Click the green v:stable menu at the bottom of the left sidebar.
3. Try to go to "latest" (or any other version)

Expected Result: The link should be to https://anymail.readthedocs.io/en/latest/sending/ (without the "index" at the end).

Actual Result

Actual Result: The menu links to https://anymail.readthedocs.io/en/latest/sending/index/ (SORRY: This page does not exist yet.)

Note that on non-index pages, the version menu works correctly (e.g., https://anymail.readthedocs.io/en/stable/sending/django_email/, built from docs/sending/django_email.rst)

[medmunds]

A source of the problem seems to be this code in footer_views:

    if page_slug and page_slug != 'index':
        if (
            main_project.documentation_type == 'sphinx_htmldir' or
            main_project.documentation_type == 'mkdocs'
        ):
            path = page_slug + '/'
     # ...

page_slug on a sphinx_htmldir subdir index page is "subdir/index" (e.g., "sending/index" in the reported example). I can't find the code that generates page slugs, which is probably the right place to fix this. (That slug should probably be just "sending".)

But an easy workaround here would be if page_slug.endswith('/index'): page_slug = page_slug[:-6] just before assigning path.

[stsewd]

Thanks! If this was working before, I can think of an incompatible change in sphinx, if this wasn't working before, then I think it's a bug. And we want to remove this magic of the documentation type #4638

[stsewd]

So, yeah, this is definitely a bug, the page slug for nested dirs is page/index while for no-nested pages is just page. Not sure if this is a breaking change in sphinx or if this was wrong the whole time, I'll try to check with some previous sphinx versions.

[medmunds]

It's very possible I'm remembering wrong that it worked before.

If RTD's page_slug is Sphinx's docname, it does seem like Sphinx's dirhtml builder has had special handling for docname.endswith(SEP + 'index') going back 10 years.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stsewd]

Still valid

[medmunds]

@stsewd happy to submit a PR if that would help. I think the fix is in footer_views.py:

    if page_slug and page_slug != 'index':
        if main_project.documentation_type == 'sphinx_htmldir':
+           if page_slug.endswith('/index'):
+               path = page_slug[:-5]
+           else:
                path = page_slug + '/'
        else:
            path = page_slug + '.html'
    else:
        path = ''

If so, I could use some guidance on where to add a test or pointers to similar tests. (test_footer.py? There don't seem to be many tests specific to sphinx_htmldir.)

[stsewd]

That should work only if the project is using only sphinx_htmldir with all the versions. We are trying to remove the project.documentation_type calls #4638

So, not sure if want to keep patching this or fix this for complete with #4638 (it may take some time)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.