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.

Sign up for GitHub

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

Jump to bottom

Previous/Next links not rendered correctly in recent PR doc build sites #502

Closed
derekocallaghan opened this issue Mar 14, 2023 · 6 comments
Closed

Previous/Next links not rendered correctly in recent PR doc build sites #502

derekocallaghan opened this issue Mar 14, 2023 · 6 comments
Labels
beam refactor documentation Improvements or additions to documentation

Comments

@derekocallaghan
Copy link
Contributor

In recent PRs, the Previous/Next links are rendered correctly in the corresponding PR doc build sites, e.g. scroll to the bottom of the following:

However, the same links in PR doc builds from this week don't look right, e.g.

I don't have a fix for this yet, but looking at the HTML source, it looks like the classes are different.

Correct rendering (e.g. #487):

<!-- Previous / next buttons -->
<div class='prev-next-area'> 
    <a class='left-prev' id="prev-link" href="[../recipe_user_guide/execution.html](view-source:https://pangeo-forge--487.org.readthedocs.build/en/487/pangeo_forge_recipes/recipe_user_guide/execution.html)" title="previous page">
        <i class="fas fa-angle-left"></i>
        <div class="prev-next-info">
            <p class="prev-next-subtitle">previous</p>
            <p class="prev-next-title">Recipe Execution</p>
        </div>
    </a>
    <a class='right-next' id="next-link" href="[xarray_zarr/netcdf_zarr_sequential.html](view-source:https://pangeo-forge--487.org.readthedocs.build/en/487/pangeo_forge_recipes/tutorials/xarray_zarr/netcdf_zarr_sequential.html)" title="next page">
    <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Xarray-to-Zarr Sequential Recipe: NOAA OISST</p>
    </div>
    <i class="fas fa-angle-right"></i>
    </a>
</div>

Incorrect rendering (e.g #500):

<div class='prev-next-bottom'>
    
    <div id="prev">
        <a class="left-prev" href="[../recipe_user_guide/execution.html](view-source:https://pangeo-forge--500.org.readthedocs.build/en/500/pangeo_forge_recipes/recipe_user_guide/execution.html)" title="previous page">
            <i class="prevnext-label fas fa-angle-left"></i>
            <div class="prevnext-info">
                <p class="prevnext-label">previous</p>
                <p class="prevnext-title">Recipe Execution</p>
            </div>
        </a>
    </div>
     <div id="next">
        <a class="right-next" href="[xarray_zarr/netcdf_zarr_sequential.html](view-source:https://pangeo-forge--500.org.readthedocs.build/en/500/pangeo_forge_recipes/tutorials/xarray_zarr/netcdf_zarr_sequential.html)" title="next page">
            <div class="prevnext-info">
                <p class="prevnext-label">next</p>
                <p class="prevnext-title">Xarray-to-Zarr Sequential Recipe: NOAA OISST</p>
            </div>
            <i class="prevnext-label fas fa-angle-right"></i>
        </a>
     </div>

</div>
@derekocallaghan derekocallaghan added documentation Improvements or additions to documentation beam refactor labels Mar 14, 2023
@derekocallaghan
Copy link
Contributor Author

It looks like this is related to the pydata_sphinx_theme version being used during the build:

Correct rendering:

Read the Docs build information
Build id: 19611213
Project: pangeo-forge
Version: 487
Commit: 67c5a06e86e78b7981f5f55fc7d682bdaf00ebc3
Date: 2023-02-27T10:57:56.442322Z
State: finished
Success: True


[rtd-command-info] start-time: 2023-02-27T10:57:57.940503Z, end-time: 2023-02-27T10:57:58.962565Z, duration: 1, exit-code: 0
git clone --no-single-branch --depth 50 https://github.com/pangeo-forge/pangeo-forge .
Cloning into '.'...

[rtd-command-info] start-time: 2023-02-27T10:57:59.408416Z, end-time: 2023-02-27T10:57:59.993208Z, duration: 0, exit-code: 0
git fetch origin --force --tags --prune --prune-tags --depth 50 pull/487/head:external-487
From https://github.com/pangeo-forge/pangeo-forge
 * [new ref]         refs/pull/487/head -> external-487

...

Collecting pydata-sphinx-theme~=0.7.2
  Downloading pydata_sphinx_theme-0.7.2-py3-none-any.whl (1.4 MB)

Incorrect rendering:

Read the Docs build information
Build id: 19764503
Project: pangeo-forge
Version: 500
Commit: a8297eee383d58e09372ec601c62cd5a13e84e0a
Date: 2023-03-13T16:59:58.638407Z
State: finished
Success: True


[rtd-command-info] start-time: 2023-03-13T17:00:00.364798Z, end-time: 2023-03-13T17:00:01.789643Z, duration: 1, exit-code: 0
git clone --no-single-branch --depth 50 https://github.com/pangeo-forge/pangeo-forge .
Cloning into '.'...

[rtd-command-info] start-time: 2023-03-13T17:00:02.130566Z, end-time: 2023-03-13T17:00:03.689418Z, duration: 1, exit-code: 0
git fetch origin --force --tags --prune --prune-tags --depth 50 pull/500/head:external-500
From https://github.com/pangeo-forge/pangeo-forge
 * [new ref]         refs/pull/500/head -> external-500

...

Collecting pydata-sphinx-theme~=0.6.0
  Downloading pydata_sphinx_theme-0.6.3-py3-none-any.whl (1.4 MB)

I have 0.7.2 installed locally, and the pydata_sphinx_theme/_templates/prev-next.html template looks correct:

In [2]: pydata_sphinx_theme.__version__
Out[2]: '0.7.2'
<!-- Previous / next buttons -->
<div class='prev-next-area'>
    {%- if prev %} 
    <a class='left-prev' id="prev-link" href="{{ prev.link|e }}" title="{{ _('previous') }} {{ _('page') }}">
        <i class="fas fa-angle-left"></i>
        <div class="prev-next-info">
            <p class="prev-next-subtitle">{{ _("previous") }}</p>
            <p class="prev-next-title">{{ prev_title or prev.title }}</p>
        </div>
    </a>
    {%- endif %}
    {%- if next %}
    <a class='right-next' id="next-link" href="{{ next.link|e }}" title="{{ _('next') }} {{ _('page') }}">
    <div class="prev-next-info">
        <p class="prev-next-subtitle">{{ _("next") }}</p>
        <p class="prev-next-title">{{ next_title or next.title }}</p>
    </div>
    <i class="fas fa-angle-right"></i>
    </a>
    {%- endif %}
</div>

derekocallaghan added a commit to derekocallaghan/pangeo-forge-recipes that referenced this issue Mar 15, 2023
@derekocallaghan
Ensure correct documentation Previous/Next template is used (pangeo-f…
025488b 
…orge#502)
@derekocallaghan derekocallaghan mentioned this issue Mar 15, 2023
Closed
derekocallaghan added a commit to derekocallaghan/pangeo-forge-recipes that referenced this issue Mar 15, 2023
@derekocallaghan
Pin pydata_sphinx_theme version (pangeo-forge#502)
d4d1379
@derekocallaghan
Copy link
Contributor Author

Pinning pydata_sphinx_theme to 0.7.2 doesn't fix the problem based on the latest build:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 1054, in handle_page
    output = self.templates.render(templatename, ctx)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/readthedocs_ext/readthedocs.py", line 185, in rtd_render
    content = old_render(template, render_context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/jinja2glue.py", line 192, in render
    return self.environment.get_template(template).render(context)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/jinja2/environment.py", line 1291, in render
    self.environment.handle_exception()
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/jinja2/environment.py", line 925, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/themes/basic/page.html", line 10, in top-level template code
    {%- extends "layout.html" %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx_book_theme/layout.html", line 30, in top-level template code
    {% set single_page = " single-page" %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/pangeo_sphinx_book_theme/../pydata_sphinx_theme/layout.html", line 2, in top-level template code
    {%- import "static/webpack-macros.html" as _webpack with context %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/themes/basic/../basic/layout.html", line 174, in top-level template code
    {%- block content %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/pangeo_sphinx_book_theme/../pydata_sphinx_theme/layout.html", line 75, in block 'content'
    {% block docs_main %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx_book_theme/layout.html", line 35, in block 'docs_main'
    {% block docs_body %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx_book_theme/layout.html", line 36, in block 'docs_body'
    {% include "topbar.html" %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx_book_theme/topbar.html", line 53, in top-level template code
    {%- include "docs-toc.html" %}
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/jinja2glue.py", line 213, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: docs-toc.html

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/application.py", line 352, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 296, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 534, in write
    self._write_serial(sorted(docnames))
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 544, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 611, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/pangeo-forge/envs/503/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 1061, in handle_page
    raise ThemeError(__("An error happened in rendering the page %s.\nReason: %r") %
sphinx.errors.ThemeError: An error happened in rendering the page index.
Reason: TemplateNotFound('docs-toc.html')

Theme error:
An error happened in rendering the page index.
Reason: TemplateNotFound('docs-toc.html')

@derekocallaghan
Copy link
Contributor Author

Hi @rabernat and @norlandrhagen, are either of you seeing this issue? I just had a look at the latest docs build for #516, and I'm still seeing it on my side, e.g.

https://pangeo-forge--516.org.readthedocs.build/en/516/pangeo_forge_recipes/tutorials/index.html

Although my previous attempt at a fix that pins pydata_sphinx_theme to 0.7.2 worked locally, it unfortunately didn't work during the PR docs build.

@norlandrhagen
Copy link
Contributor

@derekocallaghan , yeah definitely rendering strange for me.
image

@derekocallaghan
Copy link
Contributor Author

Thanks, that's what I'm seeing too

This was referenced Jul 3, 2023
Closed
Merged
@cisaacstern
Copy link
Member

cisaacstern commented Jul 3, 2023 •
edited
Loading

Closed by #534. Thanks @derekocallaghan for your attention to this!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
beam refactor documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@derekocallaghan @norlandrhagen @cisaacstern