Don't use sphinx==5.3.0 in examples

[duboism]

Hello,

I'm not sure about how to report that but the page How to create reproducible builds shows an example based on sphinx==5.3.0. The problem is that this version has some issues with formulas (see sphinx-doc/sphinx#10944). It's fixed in sphinx 6.0.1. I lost a few hours trying to understand that.

So I think that the page can just be updated with more recent sphinx versions. Sure those versions might have bugs too but a bug in formulas seems rather bad. Any thoughts ?

Thanks in advance.

[humitos]

I'm not sure about how to report that but the page How to create reproducible builds shows an example based on sphinx==5.3.0

In that documentation page we explains how to pin dependencies, regardless of the version of them used. Version 5.3.0 is definitely not the latest nor the recommended version to use. If that message is not clear, we should update one of the paragraph to communicate that clearly.

Updating the page to use version to 7.2.6. will have the exact same issue you noticed when a newer Sphinx version was released.

@duboism would you like to open a PR to clarify this in the documentation?

[duboism]

I didn't mean to suggest using the last version of sphinx (it's hard to cope as they release often) but I meant that this particular example is really unlucky (in our particular case, we didn't really payed attention to sphinx version before recent changes so I just followed the page blindly). The page is really interesting by the way (even for other python projects).

That being said, you're right: the page could state a bit more clearly that this is just an example and that it's up to the developer to check the version. I will open a PR ASAP.

By the way, the first section (Use a .readthedocs.yaml configuration file) should be rewritten since this file is mandatory, right ?

[humitos]

By the way, the first section (Use a .readthedocs.yaml configuration file) should be rewritten since this file is mandatory, right ?

Yes! Good point about this as well! 👍🏼

[duboism]

I opened #10939. It's still WIP for now. I'm not very fluent in writing docs so don't hesitate to comment.

[duboism]

#10939 is ready for review/comments.

[duboism]

After some time, #10939 is merged... Apparently, the documentation about reproducible builds was updated elsewhere so all in all, it's a very simple change...

I still think that this guide should be updated with more recent versions of sphinx to avoid mistakes.