Update to the latest version of Sphinx

[ElectrodeYT]

I have not been able to find any (bad) differences between the current live version and when using the latest version of Sphinx/Furo. As far as I can tell, the stability policy from Furo (available here), keeping both at simply the latest version available should be safe.

The ToC change is needed for the index page because it seems to generate an empty Contents list for some reason. Given the fact that the Sphinx 4.5.0 generated page has no contents bar here, hiding it here seems like the correct call.

[ElectrodeYT]

From what I can tell, the CI Failure is likely due to the PR being untrusted, according to Jenkins. I am not sure if my Jenkinsfile changes would make CI work, but I am also not sure how to verify this either.

[doniks]

From what I can tell, the CI Failure is likely due to the PR being untrusted, according to Jenkins. I am not sure if my Jenkinsfile changes would make CI work, but I am also not sure how to verify this either.

here https://ci.ubports.com/blue/organizations/jenkins/docs.ubports.com/detail/PR-594/8/pipeline it says something about sphinx version 7.2.6 not being available

+ pip install --no-cache-dir --user --upgrade -r requirements.txt

ERROR: Could not find a version that satisfies the requirement sphinx==7.2.6 (from -r requirements.txt (line 1)) (from versions: 0.1.61611, 0.1.61798, 0.1.61843, 0.1.61945, 0.1.61950, 0.2, 0.3, 0.4, 0.4.1, 0.4.2, 0.4.3, 0.5, 0.5.1, 0.5.2b1, 0.5.2, 0.6b1, 0.6, 0.6.1, 0.6.2, 0.6.3, 0.6.4, 0.6.5, 0.6.6, 0.6.7, 1.0b1, 1.0b2, 1.0, 1.0.1, 1.0.2, 1.0.3, 1.0.4, 1.0.5, 1.0.6, 1.0.7, 1.0.8, 1.1, 1.1.1, 1.1.2, 1.1.3, 1.2b1, 1.2b2, 1.2b3, 1.2, 1.2.1, 1.2.2, 1.2.3, 1.3b1, 1.3b2, 1.3b3, 1.3, 1.3.1, 1.3.2, 1.3.3, 1.3.4, 1.3.5, 1.3.6, 1.4a1, 1.4b1, 1.4, 1.4.1, 1.4.2, 1.4.3, 1.4.4, 1.4.5, 1.4.6, 1.4.7, 1.4.8, 1.4.9, 1.5a1, 1.5a2, 1.5b1, 1.5, 1.5.1, 1.5.2, 1.5.3, 1.5.4, 1.5.5, 1.5.6, 1.6b1, 1.6b2, 1.6b3, 1.6.1, 1.6.2, 1.6.3, 1.6.4, 1.6.5, 1.6.6, 1.6.7, 1.7.0b1, 1.7.0b2, 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.7.4, 1.7.5, 1.7.6, 1.7.7, 1.7.8, 1.7.9, 1.8.0b1, 1.8.0, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.8.5, 1.8.6, 2.0.0b1, 2.0.0b2, 2.0.0, 2.0.1, 2.1.0, 2.1.1, 2.1.2, 2.2.0, 2.2.1, 2.2.2, 2.3.0, 2.3.1, 2.4.0, 2.4.1, 2.4.2, 2.4.3, 2.4.4, 2.4.5, 3.0.0b1, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0, 3.2.1, 3.3.0, 3.3.1, 3.4.0, 3.4.1, 3.4.2, 3.4.3, 3.5.0, 3.5.1, 3.5.2, 3.5.3, 3.5.4, 4.0.0b1, 4.0.0b2, 4.0.0, 4.0.1, 4.0.2, 4.0.3, 4.1.0, 4.1.1, 4.1.2, 4.2.0, 4.3.0, 4.3.1, 4.3.2, 4.4.0, 4.5.0, 5.0.0b1, 5.0.0, 5.0.1, 5.0.2, 5.1.0, 5.1.1, 5.2.0, 5.2.0.post0, 5.2.1, 5.2.2, 5.2.3, 5.3.0)

ERROR: No matching distribution found for sphinx==7.2.6 (from -r requirements.txt (line 1))

WARNING: You are using pip version 20.2; however, version 24.0 is available.

You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.

script returned exit code 1

[doniks]

Not sure what determines these versions ... looks like up to 5.3.0 would be available.

To recap: You're proposal is meant to fix the currently broken local build of master. ./build.sh (After removing any old copy of the python environment in ~/ubportsdocsenv) results in the following error:

15:34 $ ./build.sh 
Build environment found in "/home/peter/ubportsdocsenv".
Building...
Running Sphinx v4.5.0
loading translations [en]... done

Sphinx version error:
The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version.

so, I can think of two options:

• you could try with 5.3.0 and see whether sphinx,furo,jenkins, everybody is happy with that
• we try to chase someone from Infrastructure team with Jenkins access why sphinx can't go higher

[ElectrodeYT]

From my small amount of research, the 5.3.0 Sphinx problem is probably related to the python version the Jenkins container currently uses.

As can be seen on PyPI, Sphinx 5.3.0 needs python 3.6, while Sphinx 6.0.0 needs python 3.8, and the current Jenkinsfile is python 3.7.

[ElectrodeYT]

I think the python container version is the cause here.

python:3.7 docker container:

^[[A[alexander@alex-computer docs.ubports.com]$ sudo docker run --rm -it --entrypoint /bin/bash python:3.7
root@8eda44e65742:/# pip3 install sphinx
Collecting sphinx
  Downloading sphinx-5.3.0-py3-none-any.whl (3.2 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.2/3.2 MB 4.7 MB/s eta 0:00:00

python:latest docker container:

[alexander@alex-computer docs.ubports.com]$ sudo docker run --rm -it --entrypoint /bin/bash python:latest
root@91dc3995efe5:/# pip3 install sphinx
Collecting sphinx
  Downloading sphinx-7.2.6-py3-none-any.whl.metadata (5.9 kB)

[ElectrodeYT]

I have updated the Jenkinsfile change to set Jenkins to use the python:3.12 container instead of python:latest. This should fix CI; I do not know, however, how to make Jenkins use the Jenkinsfile changes for CI on this PR.

[doniks]

so,

• we can pick the python version via Jenkins file, see here: https://ci.ubports.com/blue/organizations/jenkins/docs.ubports.com/detail/PR-596/7/pipeline#step-24-log-2
• however, I cannot get the whole package to build ... python 3.12 + sphinx 7.2.6 + furo 2024.1.29 still fails : https://ci.ubports.com/blue/organizations/jenkins/docs.ubports.com/detail/PR-596/7/pipeline/#step-25-log-32

@ElectrodeYT can you tell again which combination of versions of python + sphinx + furo you could build it with?

[ElectrodeYT]

(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ python3 --version
Python 3.11.7
(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ pip index versions sphinx furo
WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
ERROR: You need to specify exactly one argument

[notice] A new release of pip is available: 23.1.2 -> 24.0
[notice] To update, run: pip install --upgrade pip
(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ pip index versions sphinx
WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
sphinx (7.2.6)
Available versions: 7.2.6, 7.2.5, 7.2.4, 7.2.3, 7.2.2, 7.2.1, 7.2.0, 7.1.2, 7.1.1, 7.1.0, 7.0.1, 7.0.0, 6.2.1, 6.2.0, 6.1.3, 6.1.2, 6.1.1, 6.1.0, 6.0.1, 6.0.0, 5.3.0, 5.2.3, 5.2.2, 5.2.1, 5.2.0.post0, 5.2.0, 5.1.1, 5.1.0, 5.0.2, 5.0.1, 5.0.0, 4.5.0, 4.4.0, 4.3.2, 4.3.1, 4.3.0, 4.2.0, 4.1.2, 4.1.1, 4.1.0, 4.0.3, 4.0.2, 4.0.1, 4.0.0, 3.5.4, 3.5.3, 3.5.2, 3.5.1, 3.5.0, 3.4.3, 3.4.2, 3.4.1, 3.4.0, 3.3.1, 3.3.0, 3.2.1, 3.2.0, 3.1.2, 3.1.1, 3.1.0, 3.0.4, 3.0.3, 3.0.2, 3.0.1, 3.0.0, 2.4.5, 2.4.4, 2.4.3, 2.4.2, 2.4.1, 2.4.0, 2.3.1, 2.3.0, 2.2.2, 2.2.1, 2.2.0, 2.1.2, 2.1.1, 2.1.0, 2.0.1, 2.0.0, 1.8.6, 1.8.5, 1.8.4, 1.8.3, 1.8.2, 1.8.1, 1.8.0, 1.7.9, 1.7.8, 1.7.7, 1.7.6, 1.7.5, 1.7.4, 1.7.3, 1.7.2, 1.7.1, 1.7.0, 1.6.7, 1.6.6, 1.6.5, 1.6.4, 1.6.3, 1.6.2, 1.6.1, 1.5.6, 1.5.5, 1.5.4, 1.5.3, 1.5.2, 1.5.1, 1.5, 1.4.9, 1.4.8, 1.4.7, 1.4.6, 1.4.5, 1.4.4, 1.4.3, 1.4.2, 1.4.1, 1.4, 1.3.6, 1.3.5, 1.3.4, 1.3.3, 1.3.2, 1.3.1, 1.3, 1.2.3, 1.2.2, 1.2.1, 1.2, 1.1.3, 1.1.2, 1.1.1, 1.1, 1.0.8, 1.0.7, 1.0.6, 1.0.5, 1.0.4, 1.0.3, 1.0.2, 1.0.1, 1.0, 0.6.7, 0.6.6, 0.6.5, 0.6.4, 0.6.3, 0.6.2, 0.6.1, 0.6, 0.5.2, 0.5.1, 0.5, 0.4.3, 0.4.2, 0.4.1, 0.4, 0.3, 0.2, 0.1.61950, 0.1.61945, 0.1.61843, 0.1.61798, 0.1.61611
  INSTALLED: 7.2.6
  LATEST:    7.2.6

[notice] A new release of pip is available: 23.1.2 -> 24.0
[notice] To update, run: pip install --upgrade pip
(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ python3 --version
Python 3.11.7
(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ pip index versions sphinx
WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
sphinx (7.2.6)
Available versions: 7.2.6, 7.2.5, 7.2.4, 7.2.3, 7.2.2, 7.2.1, 7.2.0, 7.1.2, 7.1.1, 7.1.0, 7.0.1, 7.0.0, 6.2.1, 6.2.0, 6.1.3, 6.1.2, 6.1.1, 6.1.0, 6.0.1, 6.0.0, 5.3.0, 5.2.3, 5.2.2, 5.2.1, 5.2.0.post0, 5.2.0, 5.1.1, 5.1.0, 5.0.2, 5.0.1, 5.0.0, 4.5.0, 4.4.0, 4.3.2, 4.3.1, 4.3.0, 4.2.0, 4.1.2, 4.1.1, 4.1.0, 4.0.3, 4.0.2, 4.0.1, 4.0.0, 3.5.4, 3.5.3, 3.5.2, 3.5.1, 3.5.0, 3.4.3, 3.4.2, 3.4.1, 3.4.0, 3.3.1, 3.3.0, 3.2.1, 3.2.0, 3.1.2, 3.1.1, 3.1.0, 3.0.4, 3.0.3, 3.0.2, 3.0.1, 3.0.0, 2.4.5, 2.4.4, 2.4.3, 2.4.2, 2.4.1, 2.4.0, 2.3.1, 2.3.0, 2.2.2, 2.2.1, 2.2.0, 2.1.2, 2.1.1, 2.1.0, 2.0.1, 2.0.0, 1.8.6, 1.8.5, 1.8.4, 1.8.3, 1.8.2, 1.8.1, 1.8.0, 1.7.9, 1.7.8, 1.7.7, 1.7.6, 1.7.5, 1.7.4, 1.7.3, 1.7.2, 1.7.1, 1.7.0, 1.6.7, 1.6.6, 1.6.5, 1.6.4, 1.6.3, 1.6.2, 1.6.1, 1.5.6, 1.5.5, 1.5.4, 1.5.3, 1.5.2, 1.5.1, 1.5, 1.4.9, 1.4.8, 1.4.7, 1.4.6, 1.4.5, 1.4.4, 1.4.3, 1.4.2, 1.4.1, 1.4, 1.3.6, 1.3.5, 1.3.4, 1.3.3, 1.3.2, 1.3.1, 1.3, 1.2.3, 1.2.2, 1.2.1, 1.2, 1.1.3, 1.1.2, 1.1.1, 1.1, 1.0.8, 1.0.7, 1.0.6, 1.0.5, 1.0.4, 1.0.3, 1.0.2, 1.0.1, 1.0, 0.6.7, 0.6.6, 0.6.5, 0.6.4, 0.6.3, 0.6.2, 0.6.1, 0.6, 0.5.2, 0.5.1, 0.5, 0.4.3, 0.4.2, 0.4.1, 0.4, 0.3, 0.2, 0.1.61950, 0.1.61945, 0.1.61843, 0.1.61798, 0.1.61611
  INSTALLED: 7.2.6
  LATEST:    7.2.6

[notice] A new release of pip is available: 23.1.2 -> 24.0
[notice] To update, run: pip install --upgrade pip
(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ pip index versions furo
WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
furo (2024.1.29)
Available versions: 2024.1.29, 2023.9.10, 2023.7.26, 2023.5.20, 2023.3.27, 2023.3.23, 2022.12.7, 2022.9.29, 2022.9.15, 2022.6.21, 2022.6.4.1, 2022.6.4, 2022.4.7, 2022.3.4, 2022.2.23, 2022.2.14.1, 2022.2.14, 2022.1.2, 2021.11.23, 2021.11.16, 2021.11.15, 2021.11.12.1, 2021.11.12, 2021.10.9, 2021.9.22, 2021.9.8, 2021.8.31
  INSTALLED: 2024.1.29
  LATEST:    2024.1.29

[notice] A new release of pip is available: 23.1.2 -> 24.0
[notice] To update, run: pip install --upgrade pip
(ubportsdocsenv) [alexander@archlinux docs.ubports.com]$ 

[doniks]

argggghhhh Jenkins! It still fails to build. while it's literally the same change as that: https://github.com/ubports/docs.ubports.com/pull/596/files so maybe there is a difference between internal branches created inside the ubports/docs.ubports.com repo versus external ones such as from a user fork like yours .... when I look here https://ci.ubports.com/blue/organizations/jenkins/docs.ubports.com/detail/PR-594/11/pipeline the python and pip versions do not get printed. So, obviously it's using a different Jenkinsfile. Maybe the easiest is to just proceed with that PR https://github.com/ubports/docs.ubports.com/pull/596/files. I shall add your comment about --quiet just being a hacky workaround ... still need to properly check the output also

[ElectrodeYT]

Yep, thats Jenkins; iirc the thing it does is not use Jenkinsfile changes from "untrusted" PRs.

[doniks]

always another way : https://github.com/ubports/docs.ubports.com/pull/597

[doniks]

ok, so for the protocol, there are some known issues with this update, but they are not show stopping and we also need to move ahead with the version upgrade, otherwise other contributions are blocked. maybe once it's live and has more eyeballs on it someone will find ways to further improve this