Version de Sphinx

[jeanas]

Dans le commit CPython pointé par le Makefile, la version de Sphinx que demande Doc/requirements.txt est 3.2.1. Avec cela, j'obtiens

écriture... [ 21%] distutils/uploading .. howto/functional                                                                  
Warning, treated as error:
/home/jean/repos/cpython/Doc/glossary.rst:634:<translated>:1:term Sequence not found in case sensitive match.made a reference to sequence instead.
make[1]: *** [Makefile:51 : build] Erreur 2
make[1] : on quitte le répertoire « /home/jean/repos/cpython/Doc »
make: *** [Makefile:64 : all] Erreur 2

En revanche, la CI de ce dépôt se sert de 2.4.4 car le commit CPython qu'elle prend est plus ancien. Il semblerait logique de synchroniser les deux. Est-ce que quelqu'un peut confirmer ?

[JulienPalard]

Les versions de Sphinx c'est compliqué, on est obligés (côté cpython) de garder la compatibilité depuis Sphinx 1.8. Donc parfois on ne peut pas avancer aussi vite qu'on voudrait (le grand écart est parfois trop grand). Je suis même surpris de voir du 3.2.1 upstream tiens... bon if it works, don't fix it.

2.4.4 c'est ce qu'on utilise en prod (sur https://docs.python.org/3/), donc c'est bien pour tester :)

Mais c'est bien aussi de tester de temps en temps avec un Sphinx récent qui est capable de tester plus de choses, de remonter des erreurs plus pertinentes.

On pourrait mettre Sphinx 2 et Sphinx 3 dans la CI ...

(Bon j'ai fait une PR pour corriger ton issue en tout cas ;))

[jeanas]

Holà, je n'imaginais pas mettre le doigt sur un tel nid à problèmes. Il faut donc que la documentation CPython compile avec 1.8 ? Pourquoi ? Les distribs en ont besoin ? Est-ce que cela s'applique aussi à notre traduction ?

Et le serveur sur python.org tourne avec 2.4 ? Car la CI CPython a aussi 3.2. C'est risqué, on pourrait avoir des PRs qui passent la CI et ne compilent pas en prod -- enfin, si cela n'est pas encore arrivé, tant mieux, mais il vaudrait mieux éviter tout de même. Est-ce qu'on pourrait essayer de se synchroniser avec CPython et docs.python.org pour qu'au moins la version en prod soit testée par tout le monde ?

[JulienPalard]

Il faut donc que la documentation CPython compile avec 1.8 ? Pourquoi ? Les distribs en ont besoin ?

Exact, ce sont les distribs qui ont du mal à upgrader Sphinx, car pour upgrader Sphinx il faut que tous les paquets qui ont une doc qui se construit avec Sphinx suivent.

Est-ce que cela s'applique aussi à notre traduction ?

Non, pas directement, je ne suis au courant d'aucune distrib qui construit les traductions de la doc de Python, et de toute façons on traduit la syntaxe Sphinx imposée par les msgid, donc imposée par la doc de cpython, peu importe la version de Sphinx.

Et le serveur sur python.org tourne avec 2.4 ?

J'ai été un peu rapide en disant qu'on a 2.4.4. en prod, en fait ça dépend de la version de Python, pour éviter à avoir a backporter des modificaitons dûes aux mises à jour de Sphinx sur des versions de Python sur lesquelles on ne commit plus. Pour la 3.10 et 3.11 on utilise Sphinx 3.2.1.

Car la CI CPython a aussi 3.2.

Ça c'est OK, la CI test la branche main, et la branche main utilise bien Sphinx 3.2.1 en prod, désolé pour le raccourci.

Est-ce qu'on pourrait essayer de se synchroniser avec CPython et docs.python.org pour qu'au moins la version en prod soit testée par tout le monde ?

Oui, c'est un boulot qu'on fait depuis longtemps, regarde j'ai fait un joli tableau.

On y voit qu'avant on avait moultes sources de vérité (une version dans travis, une version dans azure, une version de prod, une version dans conf.py, une version dans Doc/requirements.txt, ...).

On y voit que depuis la 3.10 on a plus que deux versions : la minimum compatible dans conf.py et celle utilisée dans Doc/requirements.txt.

Plus bas on voit quelle version on constate sur docs.python.org, et on y voit bien du 3.2.1 depuis la 3.10.

Tiens j'ai regardé de plus près ce que tu disais :

En revanche, la CI de ce dépôt se sert de 2.4.4

c'est étrange, le commit sur lequel on est basé pour la branche 3.10 est cf739332bd039cd2303b58663a804f784883820d, et il contient bien sphinx==3.2.1 dans son Doc/requirements.txt... Oooohhh mais c'est que j'ai oublié de changer le sha1 dans .github, damned, y'a bien un souci ! Bon #1688 devrait corriger ça et éviter que ça se reproduise.