Website bullets and menu + and - expand/collapse items broken in 1.0.0

[FrightRisk]

Details

• Read the Docs project URL: https://dcc-ex.com/index.html

I don't know if this happened from one of our commits, but I don't think so since we don't touch any files that would have affected this, but all our bullets everywhere are gone and our menus now look like this. The underscores should be little + signs to signify expandability:

The page is published using GitHub pages and not really understanding how the entire process works, I was thinking that this action script, that seems to download things from somewhere every time we publish picked up something that broke the page. When I build the page locally, it looks fine. This is the docs.yml file:

jobs:
  build:

    runs-on: macos-latest
    steps:
    - name: Requirements
      run: brew install sphinx-doc
        && brew install enchant
        && pip3 install sphinx-rtd-theme
        && pip3 install sphinx-sitemap
        && pip3 install sphinxcontrib-spelling
    - name: Checkout repo
      uses: actions/checkout@1.0.0
    - name: Build docs
      run:  make github
        && echo 'dcc-ex.com' > docs/_build/html/CNAME
        && touch docs/_build/html/.nojekyll        
    - name: Deploy
      if: github.ref == 'refs/heads/sphinx'
      uses: JamesIves/github-pages-deploy-action@releases/v3
      with:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        BRANCH: gh-pages # The branch the action should deploy to.
        FOLDER: docs/_build/html # The folder the action should deploy.

[astrojuanlu]

Hello @FrightRisk , since the page is hosted on GitHub pages I'm transferring this issue to the appropriate repository.

Rather than the docs.yml file, do you have a link to the Sphinx build logs?

[FrightRisk]

@astrojuanlu Does this let you see what you need? I have verified that whatever version was done within the last week broke it. Version 1.0.0 has the bug.

https://github.com/DCC-EX/dcc-ex.github.io/runs/3605931059?check_suite_focus=true

I can also do screen shots and there is an option to download the raw logs or a zip file that puts each part of the run into its own folder. Doing some more digging, I can see that versions on my local machine are different than what GitHub is using:

docutils .16
sphinx 3.3.1
sphinx-rtd-theme 0.5.2
sphinxcontrib-applehelp 1.0.2
sphinxcontrib-devhelp 1.0.2
sphinxcontrib-htmlhelp 1.0.3
sphinxcontrib-jsmath 1.0.1
sphinxcontrib-qthelp 1.0.3
sphinxcontrib-serializinghtml 1.1.4
sphinxcontrib-spelling 7.1.0

in the build log, I can see it uses different versions on GitHub:

Collecting sphinx-rtd-theme
Downloading sphinx_rtd_theme-1.0.0-py2.py3-none-any.whl (2.8 MB)
Collecting docutils<0.18
Downloading docutils-0.17.1-py2.py3-none-any.whl (575 kB)
Collecting sphinx>=1.6
Downloading Sphinx-4.2.0-py3-none-any.whl (3.1 MB)

[nienn]

Hi @FrightRisk, you are using a version of the theme — 0.5.2 — that is not compatible with your html output. Could you try upgrading to the Stable version?

[FrightRisk]

Hi @nienn, What is interesting is that it works perfectly on my machine and the other team member's machines. It worked on GitHub also. But a few days ago, it broke. So it must be one of all those files, These are from the GitHub action log:

Downloading sphinx_rtd_theme-1.0.0-py2.py3-none-any.whl (2.8 MB)
Downloading docutils-0.17.1-py2.py3-none-any.whl (575 kB)
Downloading Sphinx-4.2.0-py3-none-any.whl (3.1 MB)

There are a ton more files and then dozens of these:

DEPRECATION: Configuring installation scheme with distutils config files is deprecated and will no longer work in the near future. If you are using a Homebrew or Linuxbrew Python, please see discussion at Homebrew/homebrew-core#76621

I'll try to download the same versions on my laptop and see if any of them break it for me like it does no GitHub.

[FrightRisk]

Ok, that broke it. I installed upgraded my read the docs theme on my laptop to 1.0.0 and it also corrupted the same things. And those two things are the only ones I've noticed. So versions before 1.0.0 worked fine.

In looking at the code comments and release notes, work was done on the icons for expanding and contracting menus and on the bullet lists. Here are my suspects:

Fix navigation expansion button sizes (#1067)
Align top and side navigation background colors on mobile (#1132)
Added support for deep toc levels (#1089)
Allow keyboard to toggle menu expansion (#1167)
Show keyboard focus on buttons (#1161)
Maintain aria-expanded along with .current in menu (#1151)
Fix navigation right padding on level2+ elements (#1068)

These were all updated to more recent versions:

"copy-webpack-plugin": "^5.1.2",
"css-loader": "^3.6.0",
"jquery": "^3.6.0"
"optimize-css-assets-webpack-plugin": "^5.0.4",
"webpack": "^4.46.0",
"webpack-cli": "^3.3.12",
"webpack-dev-server": "^3.11.2"
"webpack-watch-files-plugin": "^1.1.0",

And there were lots of changes to theme.js

I don't know how any of this works, I'm just looking for what changed.

[FrightRisk]

Am I the only one?? The left menu is also broken on my chrome browser on android. Can't see the hamburger to open the sidebar menu.

I told the github action to pip install with ==0.5.2 to use an older version and everything is fixed for now. I hope we can get this fixed

[SimonHeybrock]

I think you are not the only one, we have an issue with 1.0.0 in multiple projects, for example: https://scipp.github.io/release/0.8.2/

Apart from conf.py we have some customization using layout.html and theme_overrides.css.

[SimonHeybrock]

The main difference of the built docs I notice is that none of the docs pages contains a link to _static/css/theme.css with 1.0, whereas with 0.5 all pages have such a link.

[wtclarke]

Hi, I'm also having what appears to be the same issue at https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/introduction.html. No pages link to _static/css/theme.css.

[FrightRisk]

Thank you! I'll do some more testing looking at layout.html and theme_overrides.css. I still wonder if the issue numbers that led to changes as I listed above have anything to do with it. I can still test 1.0.0 here on my computer though I have reverted to 0.5.4 for the published web page.

[M00NZ1R]

Running of course

[FrightRisk]

I'm not sure what this means. Did you just roll back the changes and call it 1.0 anyway? Is it fixed? Just wondering what to do now and if it is safe to upgrade.

[benjaoming]

Closing this - not sure why I got a GitHub notification from this issue now. But we have definitely done a lot of changes, as well as new releases of docutils and Sphinx since 2021.

Thanks for reporting @FrightRisk - hope you eventually got it solved 👍