Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sphinx_rtd_theme/layout: Set url_root properly on index, don't use '#' #1025

Merged

Conversation

rkdarst
Copy link
Contributor

@rkdarst rkdarst commented Dec 7, 2020

Detailed description:

  • url_root is set to # on the index page, which layout.html tries to
    change back to '' (the empty string).
  • But, this updated url_root wasn't used in the actual location, as an
    argument to documentation_options.js.
  • Thus, clever enough templates, which tried to use
    $DOCUMENTATION_OPTIONS.URL_ROOT inside javascript would fail.
    This was manifested as broken links, which led to this issue:
    copy button <img> doesn't work with dirhtml builder, only on root page executablebooks/sphinx-copybutton#110
  • I have eventually traced that back to sphinx itself, and found that
    layout.html tried to fix the problem, but the fixed value wasn't
    used.
  • This fix works in my basic test, but I will continue with more tests.
  • Review:
    • someone more clever should examine this and make sure it makes
      sense
    • This does not have tests. Should it?

- You can see a practical demonstration of the problem, fully seeing
  the effect if it is not fixed, here (though that example uses the
  alabaster theme, the effect is the same here):
  executablebooks/sphinx-copybutton#110
- This is a copy of a fix from Sphinx.  The sphinx pull request is
  sphinx-doc/sphinx#8524

Detailed description:

- url_root is set to `#` on the index page, which layout.html tries to
  change back to `''` (the empty string).
- But, this updated url_root wasn't used in the actual location, as an
  argument to `documentation_options.js`.
- Thus, clever enough templates, which tried to use
  `$DOCUMENTATION_OPTIONS.URL_ROOT` inside javascript would fail.
  This was manifested as broken links, which led to this issue:
  executablebooks/sphinx-copybutton#110
- I have eventually traced that back to sphinx itself, and found that
  layout.html tried to fix the problem, but the fixed value wasn't
  used.
- This fix works in my basic test, but I will continue with more tests.
- Review:
  - someone more clever should examine this and make sure it makes
    sense
  - This does not have tests.  Should it?
@stsewd
Copy link
Member

stsewd commented Dec 7, 2020

Thanks, I'm not that familiar with all this, but makes sense. I'll merge after is approved upstream sphinx-doc/sphinx#8524

@rkdarst
Copy link
Contributor Author

rkdarst commented Dec 15, 2020

Merged upstream now.

@stsewd stsewd merged commit 1f7bdc1 into readthedocs:master Dec 15, 2020
@rkdarst rkdarst deleted the template-document-options-url_root branch December 16, 2020 14:11
@rkdarst
Copy link
Contributor Author

rkdarst commented Dec 16, 2020

thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants