Yopla

Le lun. 30 sept. 2019 à 12:27, Mist. GraphX <arnaud.ber...@mister-graphx.com <mailto:arnaud.ber...@mister-graphx.com>> a écrit :

    Bon comme tout les commentaires sont partis sur des solutions
    purement developpeur php a base de php doc et truc dans le genre,
    je vais rajouter ma vision d’intégrateur qui ne voit donc que le
    coté front !

> Ca c'est le genre de phrase qui a le don de me foutre en rogne.

Désolé Eric, tu sais bien que je suis un peut "blaireau" ^^ je le fait pas exprès, pour le reste j'avais certainement tout simplement pas lu assez en détail l'intégralité de tout ce qui a été écrit, ou j'ai commencé a rédiger mon mail et envoyé après ta proposition, bref …….


Le 02/10/2019 à 12:47, Eric Lupinacci a écrit :
Re,

Le mer. 2 oct. 2019 à 12:03, Ybbet SPIP <teddy.s...@gmail.com <mailto:teddy.s...@gmail.com>> a écrit :

    Est-ce qu’il y aura une fonction permettant d’extraire cette
    documentation ? Sortir un tableau ou autre pour pouvoir faire un
    rendu html dans l’espace privé.

Oui, c'est comme ça que je le vois.
Mais Arnaud pourrait peut-être nous en dire plus sur Kss et sur son API.
En tout cas, une API qui te permet de récupérer les informations et donc utilisable par Insérer Modèles, Autodoc voire d'autres.


oui désolé j'ai commencé a rédiger une réponse, mais j'ai eut un trucs sur le feu… donc,

la voici

Hello,

Le 30/09/2019 à 13:43, JLuc a écrit :
Si un format est défini pour commenter les squelettes et les modèles
il pourrait être montré "in situ" dans une évolution du ?var_mode=inclure
-- par exemple au survol des <h6> noms de noisettes.

JL

Ça resterait à implémenter mais pour le coup des noisettes (au sens noizettier) comme elles sont forcements définies par un yaml, il me semble que ce serait plus une implémentation via php, comme il est fait avec les saisies, non ?. Et du coup comme on a accès a l'edition des noisettes on a forcément accès aux paramêtres. Donc un inventaire des noisettes et params peut-être mais je suis pas sur de l'utilité vu que le noizettier est déjà très visuel comme mode de conception de pages.

Si on parle au sens inclusions, oui on est dans le cas des modèles.

Après des utilisations que j'ai faites de Kss j'ai extrait / utilise deux types de styleguide/documentations :

- une doc de type technique qui utilise les params, descriptif, titre et se raprocherait de sassdoc/phpdoc, ceci quand on documente des mixins ou fonctions de pre-processeurs css (less, stylus, scss). Ce qui pourrait convenir au besoin des modèles/inclusions, si on étend la classe en lui expliquant quels type de fichiers inspecter (https://github.com/kss-php/kss-php/blob/master/lib/Parser.php#L42), quels chemins, avec quel style de commentaires (simple regex https://github.com/kss-php/kss-php/blob/master/lib/CommentParser.php#L178).

Par contre la classe kssphp et la gestion des parameters de mon avis devrait être amélioré, pour bien les différencier et les exploiter, actuellement la regex qui extrait les param  est trop basique (j'avais fait un proposition pour le typage - entre autre -  mais ça à pas été retenu ^^ parceque c'est pas dans la spec)

https://github.com/kss-php/kss-php/blob/master/lib/Section.php#L289

https://github.com/kss-php/kss-php/blob/master/lib/Parameter.php

prend tout ce qui est de la forme

`quelquechose - description`

donc on peut passer soit

```

$mavar - description
@var - desc
@param monparam {int} (16 !) - monparam desc

etc,

```

un exemple complet

https://gitlab.com/mister-graphx/fragments/framework/blob/4.0.0/src/addons/ui-kit/_icons.scss


la effectivement si c'est pour faire une doc purement technique des inclusion et modèle, autodoc est peut être plus à même déjà de produire ce type de doc, avec phpdoc ...

- une doc plus visuelle axé css qui elle présente des preview de composant, et qui documente les extenders ou modifiers css, le markup attendu, le javascript éventuel, le comportement suivant les breakpoints. Plus utile pour présenter un design system, un état des lieux des composants et les classes css qui les étende ou modifie. Notamment ça peut être utilisé aussi comme outil pour déceler des régressions entre deux versions du thème.


La classe retourne un objet, par sections dans le cas de mes test en plugin spip, je transformais en json et je l'utilisais via une boucle data. Niveau perf ça peut sur des gros volumes ou path faire beaucoup de calculs, surtout que dans le cas des css en dev on n'utilise ni compression, ni cache sinon plus de commentaires, modifs pas a jour.

Dans le cas des inclusions / modèles ça reviendrait aussi dans un var_mode inclure a recalculer et récupérer les sections de doc pour les associer ensuite au bon endroit dans le dom (aucune idée de comment ^^ je n'ai pas fureté dans cette partie du code de spip). La pour le coup de la perf et des calculs, du cache, j'avoue que je suis certainement pas le plus performant ;-) le truc c'est que si on enlève les commentaires y'a plus de doc, donc faut le faire au moment oportun vu qu'on est dans des REM je sais pas a quel moment spip les vire.

Si c'est juste une page qui liste les modèles/inclure, et leurs params ça c'est assez "simple" a faire.

Voila, sinon la classe kssphp est relativement simple et facile a détourner , le code est structuré et clair, je la trouve plus facilement détournable et adaptable que phpdocumentor pour en faire ce que l'on veut mais c'est surement due a mon niveau en php. Tout dépend de ce que l'on souhaite comme niveau de complexité ou d’interaction au final.

Il existe des implémentations mais qui s'occupe uniquement de styleguide (partie visuelle) pour Node

KssNode avec quelque ajouts a la spec KSS (mais ça génère du statique, pour moi une styleguide ça doit être dynamique  )

https://github.com/kss-node/

Un module pour Drupal aussi est sorti (je l'ai vu passer mais pas testé) la on est sur de la living style guide

https://www.drupal.org/project/kss

je peut essayer de prendre le temps de déposer sur gitlab le début de plugin spip que j'avais commencé  et qui ne s’occupe pour le moment que des styles (css/scss), si ça a un intérêt quelconque, voir rajouter la prise en charge des modèle pour tester, Dites moi …


--
Bonne journée
Arnaud B. (Mist. GraphX)

----
spip-zone@rezo.net - https://listes.rezo.net/mailman/listinfo/spip-zone

Répondre à