requirements.txt updates

[deb-intel]

sphinxcontrib-applehelp was recently updated to 1.0.6. This caused a series of compatibility issues between sphinxcontrib-applehelp, sphinx, and breathe, which caused all recent builds to fail. To lessen this problem both now and in the future, we removed hardcoded software versions in the requirements.tx file although we updated sphinx to 7.0 or higher. This will enable the system to pick compatible software versions to match our needs.

[mwasko]

sphinxcontrib-applehelp was recently updated to 1.0.6. This caused a series of compatibility issues between sphinxcontrib-applehelp, sphinx, and breathe, which caused all recent builds to fail.

It looks like a gap in the requirements list to point to specific sphinxcontrib-applehelp version?

To lessen this problem both now and in the future, we removed hardcoded software versions in the requirements.tx file although we updated sphinx to 7.0 or higher. This will enable the system to pick compatible software versions to match our needs.

How this approach is going to guarantee that our SOF documentation will compile successfully with latest tools version?

[lgirdwood]

sphinxcontrib-applehelp was recently updated to 1.0.6. This caused a series of compatibility issues between sphinxcontrib-applehelp, sphinx, and breathe, which caused all recent builds to fail.

It looks like a gap in the requirements list to point to specific sphinxcontrib-applehelp version?

To lessen this problem both now and in the future, we removed hardcoded software versions in the requirements.tx file although we updated sphinx to 7.0 or higher. This will enable the system to pick compatible software versions to match our needs.

How this approach is going to guarantee that our SOF documentation will compile successfully with latest tools version?

IIRC, we align with the same versions used by the Zephyr docs (as SOF docs and Zephyr docs use the same framework). @deb-intel is my understanding still correct ?

[deb-intel]

@mwasko @lgirdwood When @intelkevinputnam and I built SOF locally, the build set the proper requirements based on our setting Sphinx to >=7. It automatically new to use sphinxcontrib-applehelp version 1.0.4 instead of 1.0.6 as well as the best version of breathe. The build kept failing because we kept giving it specific versions. I think this will continue to happen every time breathe, docutils, and software we didn't even know about (such as -applehelp) makes updates.

[deb-intel]

IIRC, we align with the same versions used by the Zephyr docs (as SOF docs and Zephyr docs use the same framework). @deb-intel is my understanding still correct ?

@lgirdwood I am not familiar with how Zephyr handles things. I know they no longer have a full-time doc person. I'll ask one of our guys if he can see what's up with their requirements.

[intelkevinputnam]

I recommend moving to version 7 of sphinx. A good option for a specific version is 7.1.2 as this will have the broadest compatibility for those who might want to build it locally (later versions require Python 10 or better).

[lgirdwood]

Thanks @deb-intel @intelkevinputnam for explaining.

[lgirdwood]

@mwasko good for you now ?

[marc-hb]

When @intelkevinputnam and I built SOF locally,

What is "locally"? Ubuntu, Fedora, other? Which version? Each distribution and even each user has a different combination. Versions were hardcoded in requirements.txt to solve that problem (We already have requirements-lax.txt for more flexibility)

The build kept failing because we kept giving it specific versions.

In that case you just un-hardcode locally and temporarily, find a complete set of versions that works (as you already did) and then snapshot and hardcode that combination. Problem solved for everyone and for a long time as opposed to just on one system for a short time. That has been working and it can work again.

It looks like a gap in the requirements list to point to specific sphinxcontrib-applehelp version?

Yes of course. The solution was to hardcode MORE, not less.

I think this will continue to happen every time breathe, docutils, and software we didn't even know about (such as -applehelp) makes updates.

It will for sure happen again very soon now that all the versions are un-harcoded. In fact it's already happening:

• Using requirements-lax.txt I just hit this recent regression on my system: 4.1.0 release: Invalid C++ declaration: Expected identifier in nested name sphinx-doc/sphinx#9433 People have been avoiding it by... hardcoding.

• blockdiag is now orphaned ('ImageDraw' object has no attribute 'textsize' warning with new pillow version 10.0.0 #472). We have been (and still are!) avoiding that failure by hardcoding pillow (73ac8f5)

• etc.

PS: I spent days finding combinations that work, please copy me next time.

[marc-hb]

The comment still says "This file hardcodes..."