Bonjour à tous,
Comme indiqué avant l’été, nous avons bien avancé sur une refonte de la documentation.
Voilà un sommaire vers la documentation en francais et un autre vers la documentation en anglais.
Nous avons choisi de nous appuyer sur la méthode diataxis pour construire cette documentation. Si vous décelez des incohérences, des manques et que vous souhaitez nous aider à l’améliorer, faites le nous savoir !
Au plaisir de nos futurs échanges
Anne-Laure, pour l’équipe GarganText
Merci beaucoup pour ce superber travail réalisé en si peu de temps, un big hug à tous 
Bonjour,
Quelques commentaires ci-dessous.
Merci pour ce gros travail de documentation sur ce que permet de faire gargantext !
L’édition de cette documentation étant visiblement ouverte au public, je me suis permis de corriger une typo sur la version française uniquement, concernant le lien de la section :
2.3.C. Etape 3 : L’analyse au niveau des auteurs, des institutions et des sources
qui avait hhttps:// au lieu de https://.
Envisagez-vous de mettre cette documentation directement avec le code source d’haskell-gargantext ? C’est à mon humble avis l’endroit le plus attendu, pérenne et encourageant l’actualisation au moment même où un changement du code source le nécessite ; c’est ce que font notamment Linux ou le compilateur Haskell GHC).
Remarque : auquel cas il faudra utiliser des liens relatifs vers les différences pages, et en profiter pour donner des noms à ces pages à la place des identifiants à 64 chiffres hexadécimaux de CodiMD.
Dans cette 4° catégorie du plan Diátaxis, il serait à mon avis attendu de mentionner la documentation générée par Haddock à partir du code source Haskell. Le plus attendu pour cela serait qu’haskell-gargantext soit publié sur la plateforme Hackage et d’y renvoyer (cela peut, ou non, s’accompagner d’un sponsorship et/ou d’une affiliation à la Haskell Foundation).
Cependant, haskell-gargantext n’est pas publié sur Hackage. Une des raisons techniques qui j’imagine joue un rôle important est l’utilisation de dépendances hors-Hackage, ce qui empêcherait probablement Hackage de générer la documentation (et encore, de nos jours l’existence du fichier cabal.project.freeze fournit toutes les informations qu’il faut sur les dépendences Haskell, Hackage pourrait éventuellement s’en servir, mais je ne sais pas si c’est le cas).
Apparemment une telle documentation Haddock a été un jour publiée sur https://doc.gargantext.org mais ce site est malheureusement en erreur depuis au moins plusieurs mois de ce que j’en vois.
Je peux suggérer trois étapes pour avancer sur ce point, du plus immédiat au plus satisfaisant :
haskell-gargantext et ses dépendances originales (gargantext-prelude, gargantext-graph, …) pour les remettre sur https://doc.gargantext.org.haskell-gargantext en juin dernier, cela ne marchait pas pour une broutille de commentaires mal compris par Haddock, mais facilement corrigable.haskell-gargantext et ses dépendances originales sur Hackage, et générer soi-même leur documentation Haddock pour les envoyer sur Hackagecabal haddock --haddock-for-hackage).Bonjour,
Merci julm pour ton retour sur la documentation et ton aide pour le projet en général!
Je suis tout à fait d’avis de pointer vers la documentation du code, à la fois backend (Haskell) et frontend (Purescript). Ok pour la 4° catégorie mentionnée.
Le rapprochement avec Hackage et la Haskell Foundation est en cours, nous stabilisons le projet encore et c’est pour bientôt.
Pour être précis au sujet de la documentation du code pour les développeurs:
Effectivement j’avais commencé avec doc.gargantext.org mais cela pose plusieurs problèmes:
Je propose donc que chaque instance en production pour ses utilisateurs génère sa propre version de la documentation pour éviter les mauvaises interprétations (ce qui suppose d’adapter le lien dans l’interface). C’est strictement conforme à la licence GarganText utilisée (AGPL/CECILL…)
Mais je n’ai pas eu le temps de voir comment faire pour forcer le lien de la doc générée par haddock et servir cette partie via l’instance de prod. C’est une issue sur laquelle on pourrait travailler ensemble.
Je vais commenter le lien dans l’interface mais idéalement, chaque lien devrait pointer vers la bonne version de doc utilisée par l’instance elle même comme le nécessite la licence d’utilisation du code.
Au plaisir d’en discuter.
Alexandre
Merci julm pour ton retour sur la documentation et ton aide pour le projet en général!
Avec plaisir, c’est vraiment pas grand chose, surtout comparé au travail que vous avez abattu pour faire ce nouveau gargantext.
Le rapprochement avec Hackage et la Haskell Foundation est en cours, nous stabilisons le projet encore et c’est pour bientôt.
Oh ! Intéressant 
Le reste de ce (trop long) message est probablement aussi trop technique (entendre : ça cause Haskell) pour le Discourse, je le pose ici tout de même car je n’ai pas de meilleur endroit (le Gitlab de l’ISC-PIF n’est pas ouvert au public).
Mais je n’ai pas eu le temps de voir comment faire pour forcer le lien de la doc générée par haddock et servir cette partie via l’instance de prod
[…]
Je propose donc que chaque instance en production pour ses utilisateurs génère sa propre version de la documentation
Hmm, si je comprends bien ta proposition, pour la partie Haskell (je ne sais pas pour Purescript) il devrait être possible de faire cela en utilisant le champ version (voire aussi homepage) renseigné dans gargantext.cabal et accessible dans PackageInfo_pkgname (un module autogénéré tout comme le Paths_pkgname déjà utilisé par haskell-gargantext).
Exemple à la va-vite pour être clair (mais pas testé) :
import qualified PackageInfo_gargantext as PackageInfo
docBaseUrl = PackageInfo.homepage <> "/haskell-package"
docUrl = docBaseUrl <> "/gargantext-" <> show PackageInfo.version
Le frontend devrait ainsi pouvoir recevoir du serveur cette URL docUrl qui lui correspond précisément.
Par défaut ce serait donc vers https://gargantext.org/haskell-package/....
Mais se pourrait être vers https://mon-fork-de-gargantext.org/haskell-package pour un fork de haskell-gargantext, qui n’aurait qu’à (et probablement devrait) modifier le champ homepage du gargantext.cabal pour cela.
Du reste https://gargantext.org/haskell-package/* pourrait à terme n’être qu’une redirection HTTP(s) vers https://hackage.haskell.org/package/*.
Si la documentation à la Diátaxis est incorporée à haskell-gargantext.git, la même approche de générer et publier cette documentation (depuis des fichiers Markdown ou quoi) à chaque version, puis de pointer vers la version correspondante, pourrait également fonctionner.
Remarque : L’occupation mémoire d’une telle approche est négligeable au vu des capacités de stockage actuelle, au pire si ça devient un sujet un jour, genre dans 1000 ans, il sera toujours possible d’utiliser sur le serveur un système de fichiers gérant de manière transparente la compression, voire la dé-duplication (comme ZFS).
Par contre, pour inclure le commit git précis dans l’URL, ça se complique, car lorsque le build est fait “out-of-tree” (comme avec nix ou cabal v2-install) alors les méta-données de git ne sont plus accessibles ; et donc passer par du TemplateHaskell pour lancer des commandes git comme le font gitrev ou githash ne marcherait plus.
Ce n’est très probablement pas utile de générer la documentation Haddock ou Markdown pour chaque commit (à chaque version comme précédemment c’est déjà top), mais c’est toujours intéressant d’afficher à l’utilisateur·rice final·le le commit Git afin d’identifier très précisément le code utilisé dans les rapports de problèmes.
flake.nix
Avec l’approche par flake.nix que j’ai explorée précédemment, une piste (que je n’ai pas encore essayée) serait d’écrire (genre lors de la patchPhase), la valeur de self.rev dans un fichier genre meta/version, listé dans le champ data-files: de gargantext.cabal, puis de le récupérer avec Paths_gargantext.getDataFileName "meta/version".
À noter qu’en plus de la rev(ision) (ici le commit Git), le flake.nix permet d’avoir les médadonnées suivantes : lastModified, lastModifiedDate, narHash, outPath (probablement la plus importante après rev), revCount, shortRev, submodules.