Documentation | Add requirements.txt (!108)

[W S (@Opifex)]

W S commented on a discussion: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/108#note_117627


> Until someone comes along with a distro or OS version that can only run newer versions of some of the packages than are on the list. 

AFAIK that should not be possible. The venv is supposed to prevent this. The only issue I can potentially see is a future Python version causing compatibility problems. A solution for that would be to freeze the Python version as well, but that can't be done through the requirements.txt. I also would not recommend it at this point. Because this **would** create a hassle for new, non-technical users. 

(P.s. note that without the use of the requirements.txt this can also be an issue: the main RTEMS repository currently is sort of broken for Python3.12 and up. I know the issue has been mentioned a couple of times on Discord, but as far as I can tell no one has made an Issue yet. I will try to create one later today, because I was one of the affected users :) )

> They're probably a newcomer and not an expert on your documentation build system, so they have no idea how to fix the configuration.

Which is precisely why this list comes in handy. It gives the non-expert a beginner friendly and failsafe way of installing packages, instead of digging through a README that may or may not have up-to-date and complete instructions on how to install it on their OS.

(Note that they don't _have_ to use it. If they want to do it the hard way, they're still free to do so. This requirements.txt merely provides a pythonic and standardized way of installing the packages)

> The packages building the docs for the release documentation do not match this list. We can tolerate older versions of some packages than in this list.

The requirements.txt of this PR was made based on the README. However, I indeed did not pay attention to the versions specified in that document. (Note that the instructions on how to install them also will not install the specified versions!)

I guess it would be a fair request to let the versions of the requirements.txt match the ones of the README.

> It will need maintaining over time. We have had to raise the base level of sphinx a few times because of breakages.

Can you explain how it broke? I can only think of three ways it can break:

1. The package was updated, causing things that worked before to no longer work as expected
2. Another package was updated, causing a conflict with the package that broke
3. Someone made a change, which turned out to create an undesired effect. Updating solved it. 

Case 1 and 2 would have been prevented by pinned versions in a requirements.txt. Case 3 can always happen, regardless of using pinned versions or not, regardless of using a requirements.txt or not. It will always be a responsibility of the one making a change to make sure that he does not break anything, and if he does, he fixes it. 
Active maintenance of this file is not needed and even not desired. It would do more harm than good. It should only be updated when there is an actual need for a change.

> Please do not get me wrong, I like idea of a list so I am wanting to understand the liabilities the project accepts if we merge it.

Don't worry. I don't mind explaining things :) But on the other hand, I'm also aware that I'm not an all-knowing super-being that's always right. So after explaining my position, I will accept you guys' consensus without any resistance :smile:

-- 
View it on GitLab: https://gitlab.rtems.org/rtems/docs/rtems-docs/-/merge_requests/108#note_117627
You're receiving this email because of your account on gitlab.rtems.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/bugs/attachments/20250108/ab921f3c/attachment.htm>