search

thesofproject / sof-docs

Documentation for SOF
Other
18 stars 73 forks source link

requirements.txt updates #485

Closed deb-intel closed 7 months ago

deb-intel commented 7 months ago

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 commented 7 months ago

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 commented 7 months ago

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 commented 7 months ago

@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 commented 7 months ago

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 commented 7 months ago

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 commented 7 months ago

Thanks @deb-intel @intelkevinputnam for explaining.

lgirdwood commented 7 months ago

@mwasko good for you now ?

marc-hb commented 7 months ago

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:

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