RTD ne builde plus notre documentation

[pierre-24]

Depuis début juillet,

Voir, à priori, readthedocs/readthedocs.org#3006

[pierre-24]

@firm1 (parce que toi je pense que tu l'as) et/ou @zestedesavoir/infrastructure ... Y'a une question à laquelle je sais pas répondre sur readthedocs/readthedocs.org#3006, y'aurais moyen de me donner temporairement l'accès au compte de zds sur rdt ou d'y répondre à ma place ?

[vhf]

Je ne sais pas comment s'y connecter, je n'ai pas d'identifiants.

[pierre-24]

M'en doutait un peu, et je suis quasi sur que @firm1 les as.

[firm1]

Normalement @vhf a réussi a récupérer les accès à Readthedocs.

[pierre-24]

Bon, j'ai essayé dans tout les sens (créer un nouveau projet, build avec ou sans virtualenv, tripoter des options du coté de RTD, tripoter des options du coté de notre setup.py), RTD ne VEUT PAS compiler notre documentation. Rien n'y fait.

[motet-a]

Du coup, on laisse tomber RTD ? C’est pas forcément la peine de perdre plus de temps avec.

[AmarOk1412]

Bah maintenant, les pages n'existent plus.

La question c'est on la laisse juste sur le github du coup ?
On remet en place le wiki ?

On fait la proposition de @vhf :

Pourquoi pas docs.zestedesavoir.com hébergé par github pages ?

ça va permettre de régler #3708

[pierre-24]

Chui pour tenter un test avec github page :)

[artragis]

Je vais voir d'ici la fin de la semaine si je peux pas lier le build au compte zds-bot.

[roipoussiere]

So, now that I can check, this project and that one have the same configuration, and are based on the same github repo. The second one is just a fork of the first one. But the build of the first one systematically fails (no matter the version, the branch or the tag), while there is no problem with the second. And I really don't understand why.
pierre24

C'est vrai que c'est super chelou...

[AmarOk1412]

Ok.
Alors je viens de foutre gh-pages sur https://amarok1412.github.io/ pour tester de mon côté.

Je vais tenter de traduire tous les .rst de RTD en .md pour le foutre sur la branche gh-pages ce week-end, revoir un peu la structure de la doc pour éviter les doublons, les trucs pas à jour, etc.

Ensuite faudra que @zestedesavoir/infrastructure redirigent https://docs.zestedesavoir.com vers https://zestedesavoir.github.io/zds-site/

On aura moins de documentation partout déjà. C'est cool que les choses cassent :D

(Note : faudra aussi passer de bower à yarn, mais je vais faire une issue à part dès que ça est prêt).

[motet-a]

Cool !

Du coup, tu vas retirer la partie de la doc générée automatiquement par le backend, non ?

Je pense que ça serait bien de construire la doc avec les assets de ZdS, histoire que le CSS soit à jour surtout. Mais ça risque de demander qu’on laisse la doc dans le dépot de ZdS.

[pierre-24]

On est obligé de repasser sur une doc en MD, et ne pas la faire générer par Travis ou une histoire comme ça ? (vraie question)

Parce que par exemple, on va perdre la "documentation technique du back" :(

[motet-a]

On est obligé de repasser sur une doc en MD, et ne pas la faire générer par Travis ou une histoire comme ça ? (vraie question)

Vu comment est parti @AmarOk1412, oui. Sinon il faut s’y prendre autrement (par exemple, garder Sphinx, compiler un site statique et push tel-quel vers les pages de GitHub).

---

Let’s bikeshed now.

<bikeshedding>Personnellement, je préfère Markdown à reStructuredText. Je doute que la partie de la doc générée automatiquement par le backend soit très utile et très utilisée (dites-moi si je me trompe), je l’enlèverai, ça complique vraiment le build pour pas grand-chose. Mais je pense que je resterait avec Sphinx et RTD, je trouve que ça fait toujours un peu moins de choses à maintenir. Et on devrait facilement pouvoir construire un site static et déployer vers GitHub Pages avec.</bikeshedding>

[pierre-24]

Si je devais défendre Sphinx (et ReST) ici, je dirais les choses suivantes, dans l'ordre de l'importance que j'y attache:

• Construction automatique de table des matières, des liens qui vont avec et d'une recherche.
• autodoc. Moi ça m'arrive de l'utiliser,
• Des éléments de syntaxe plus complet que markdown (par exemple, tout ce qu'on désigne par blocs dans notre markdown), mais c'est vrai qu'on les utilise assez peu.

[motet-a]

Note que l’on peut parfaitement utiliser Sphinx avec du Markdown, et ça marche super bien : https://github.com/motet-a/liblapin-tutorial

En fait, il y a juste un tout petit peu de reStructuredText pour la table des matière. Comme ça on garde le meilleur des deux mondes 🙃

[pierre-24]

Ah, ça, je dis pas. C'est justement pour ça que j'ai mis ReST lui même en troisième point, avant les deux premiers qui sont dû à Sphinx. Faudrait justement voir les cas ou ReST est pertinent par rapport à MD, mais comme @AmarOk1412 va passe dessus, il saura probablement répondre à ça :)

[pierre-24]

(à noter que certaines de nos docstrings sont pleines de ReST)

[firm1]

Pour la petite histoire, à l'époque le problème que l'on trouvait aux gh-pages c'était que, puisque tout ça était sur une branche séparée on ne pouvais pas dans une même PR mettre à jour le code et sa documentation. Aujourd'hui c'est pratique avec RTD pour s'assurer que l'on merge une fonctionnalité dans son ensemble (une fonctionnalité devant toujours être accompagnée de sa documentation).

[motet-a]

Je ne vois pas trop pourquoi tout changer en fait. À mon avis, c’est assez facile de laisser le dépot zds-site tel quel et de mettre un petit service qui compile la doc et qui commit le HTML dans un autre dépot, celui des gh-pages.

[AmarOk1412]

@pierre-24 mmh, en effet, je vais éviter d'aller trop vite.

Surtout sur ce point Construction automatique de table des matières, des liens qui vont avec et d'une recherche, perdre ça serait pas cool amha...

[AmarOk1412]

@pierre-24 j'ai vite fait regardé ce soir pour voir ce que j'allais faire. Je pense que je compte passer sphinx et mkdocs http://www.mkdocs.org/ pour les fichiers qui restent, compiler et publier sur le gh-pages.

Comme ça, ça permet de garder notre doc écrite, la doc générée pour le back-end, laisser les PR sur dev et garder la recherche (en plus, mkdocs a un thème readthedocs, ça sera comme si ça avait toujours compilé :) )

Pour la syntaxe, pas le temps de chercher plus que ça maintenant, mais si je peux rester au .rst je le ferais, sinon on risque de perdre 2/3 blocs. (à priori mkdocs ne supporte pas le .rst, à voir sur leur irc...)

[pierre-24]

Ok. Si jamais, il y a peut être quelque chose à creuser par là (avec cette extention qui rajoute automatiquement le .nojekyll, quoique ce soit ;) )

[motet-a]

Si ça fait juste un touch .nojekyll…

[AmarOk1412]

Ok alors des petites nouvelles vu que je n'ai pas eu le temps de compléter ça ce week end...

Mais au final, juste sphinx ça fonctionne (cf https://amarok1412.github.io/), pas besoin d'autre choses.

Bref l'idée au final, c'est dans un nouveau job Travis, on fait un make html qui nous donne notre site de docs (qu'il faut que je complète avec la doc éparpillée), puis ce job fait un petit git add dossier, git amend puis git subtree split --branch build_doc --prefix target/doc/build restera à push la branche build_doc sur gh-pages.

Comme ça @pierre-24 on garde les avantages de sphinx, et pour @firm1 on garde la docs sur master :)

[AmarOk1412]

Bon je suis enfin entrain de faire la PR, elle devrait apparaitre ce soir.

J'ai ajouté une page de doc venant du github-pages actuel, juste enlevé la partie du scss qui n'est plus à jour avec le gros travail des dernières semaines de @motet-a.

Pour le wiki, vu que les quelques pages qui y étaient ont été supprimées car inutiles, c'est fait :)

[AmarOk1412]

Fixed http://docs.zestedesavoir.com/!

[abdelaz3r]

J'ai ça :

La connexion n’est pas sécurisée

Les propriétaires de docs.zestedesavoir.com ont mal configuré leur site web. Pour éviter que vos données ne soient dérobées, Firefox ne s’est pas connecté à ce site web.

Ce site a recours à HTTP Strict Transport Security (HSTS) pour indiquer à Firefox de n’établir qu’une connexion sécurisée. Ainsi il n’est pas possible d’ajouter d’exception pour ce certificat.```

[pierre-24]

Faut qu'on demande un certif' a certbot, nan ?

[vhf]

Non. Vous devez attendre que vos DNS se mettent à jour.

[abdelaz3r]

Ok ok