search

zestedesavoir / zds-site

Cœur du projet technique de Zeste de Savoir
https://zestedesavoir.com
Other
268 stars 162 forks source link

Documenter le fonctionnement du site (front) #1357

Closed SpaceFox closed 9 years ago

SpaceFox commented 10 years ago

Aujourd'hui un développeur qui arrive sur le site et qui veut contribuer au front ne sait pas vraiment par où commencer.

On a des bouts de documentation à droite à gauche, mais aucun point d'entrée qui permettrait à un débutant de savoir par où commencer et où se renseigner en cas de doute.

Ce devrait être un fichier Markdown dans le dépôt avec les autres. Il peut contenir des liens vers des ressources externes si elles sont pérennes.

Alex-D commented 10 years ago

J'avance sur la documentation petit à petit, le tout en local pour l'instant.

SpaceFox commented 10 years ago

Peut-on avoir un point d'avancement ici ? J'ai du mal à savoir dans quelle mesure la doc est avancée (le front n'est pas du tout mon boulot, donc c'est pas facile pour évaluer) et le dernier commit sur la branche date du 12 septembre.

Alex-D commented 10 years ago

Je n'ai pas des masses de temps en ce moment. Le peu de temps que j'ai, je le passe sur le code plutôt que la doc.

En gros tu peux voir dans la sidebar les ticks verts sont les parties finies, la fiole = en cours, et rien = y a rien :/

firm1 commented 9 years ago

Je ne sais pas si c'est ici qu'il faut poster ou sur le forum, mais dans le doute je le fais ici.

Actuellement la documentation existante du front est sur une branche orpheline du depot ce qui pose plusieurs soucis.

Tout ceci a pour conséquence que les mise à jours de la doc (qui se font rares ces jours ci) ne sont pas contrôlés, et donc si on donne le lien de cette doc, il faudrait s'assurer un minimum de sa qualité. Parce que quand on tombe sur cette page et que l'on voit que c'est une partie désignée comme "finie" alors qu'il y'a des bugs sur le rendu, on pourrait se demander si a doc est vraiment utilisable.

Alex-D commented 9 years ago

Y'a t-il une raison particulière pour ce choix ?

Comment est-ce qu'on fait une démo du code si on utilise un truc du genre readthedoc ? Impossible à moins d'avoir des iframes partout qui vont pointer sur un tas de fichier HTML et encore, ça sera pas possible de faire certaines choses sans ouvrir une nouvelle fenêtre, là où la doc telle qu'elle est actuellement peut le faire (header, footer, sidebar, etc.).

une fonctionnalité doit mettre à jour la documentation en conséquence

Suffit de faire 2 PR.

On a aucun moyen (en tout cas je ne le connais pas) de juger du rendu de la doc avant d'avoir commiter sur la branche isolée

En local le truc tourne pareil qu'en ligne, je ne vois pas le soucis à ce niveau là.

quand on tombe sur cette page

C'est à cause du fait que je sois obligé de rebalancer le style à la main à chaque mise à jour de dev puisque la version en prod est toujours en retard (ce qui est logique).

SpaceFox commented 9 years ago

Suffit de faire 2 PR.

Super pratique à l'utilisation : "tu dois aussi faire une PR sur une autre branche pour mettre à jour la doc front". Très pratique aussi pour vérifier la cohérence de la doc avec la PR.

Ne pourrait-on pas réintégrer ceci à sa place, i.e. dans les branches principales ?

Alex-D commented 9 years ago

Il faut que je regarde si on peut mettre une partie de la doc (le markdown) sur dev et le conteneur sur gh-pages.

Ainsi on aurait la doc en texte en local, le rendu en ligne (et en local en faisant un checkout) et on pourrait maintenir la doc sur dev.

firm1 commented 9 years ago

Ainsi on aurait la doc en texte en local, le rendu en ligne (et en local en faisant un checkout) et on pourrait maintenir la doc sur dev.

Ce serait vraiment l'idéal selon moi.

C'est à cause du fait que je sois obligé de rebalancer le style à la main à chaque mise à jour de dev puisque la version en prod est toujours en retard (ce qui est logique).

Ok je vois.

Comment est-ce qu'on fait une démo du code si on utilise un truc du genre readthedoc ? Impossible à moins d'avoir des iframes partout qui vont pointer sur un tas de fichier HTML et encore, ça sera pas possible de faire certaines choses sans ouvrir une nouvelle fenêtre, là où la doc telle qu'elle est actuellement peut le faire (header, footer, sidebar, etc.).

Ne pourrais t-on pas imaginer d'appliquer tout simplement le css de zds à l'ensemble de la doc sphinx ?

Alex-D commented 9 years ago

Ne pourrais t-on pas imaginer d'appliquer tout simplement le css de zds à l'ensemble de la doc sphinx ?

Si tu veux, mais personnellement je ne m'en chargerais pas et ça ne doit pas affecter les fichiers du projet, uniquement les fichiers de la doc ou le générateur (aucune idée de comment ça fonctionne).

J'ai codé en truc rapido avec AngularJS pour proposer un truc qui tourne assez vite et sans me casser la tête, maintenant si vous avez envie de mettre ça dans Sphinx, c'est comme ça vous chante, moi je ne sais pas faire et je n'ai pas envie de savoir le faire.

Situphen commented 9 years ago

Bon, maintenant que la doc front est sur Sphinx, est-ce que le contenu vous convient ou vous voulez plus d'explications ? :)

firm1 commented 9 years ago

Il faudra peut-être penser à rajouter un bloc sur les problèmes qui peuvent survenir lors du build et comment les résoudre.

Un peu comme le problème que j'ai rencontré dans cette issue

sandhose commented 9 years ago

Comme dit sur l'issue, le problème est à priori réglé si tu es en virtualenv ; de plus, ça reste très rare comme cas de figure (faut le combo gyp + virtualenv, sachant que normalement, même quand tu build chromium ou android, tu installe pas gyp globalement, mais dans un chroot...)

Situphen commented 9 years ago

Bon, je pense qu'ici on est bon, non ? Surtout qu'il y a #2641 qui sera bientôt mergée !

Situphen commented 9 years ago

Bon, je pense que le front est assez documenté aujourd'hui pour pouvoir fermer le ticket !