Votre documentation d'extension, vous le gérez comment ?

[elecoest]

Hello,

Petite question, la doc de votre module, plugin, composant,... vous le gérer comment ?

genre à chaque nouveau paramètre ? vous mettez à jour une page de documentation ? vous avez un template pour ce type de documentation ?

Merci les amis.

[elecoest]

Re : Votre documentation d'extension, vous le gérez comment ?

suite à plusieurs question en privé, ma question est : comment bien afficher les informations sur ses plugins, modules, pages, paramètres... dans sa documentation.

Avec marknotes, j'ai développé ce WE un générateur de doc au format Markdown. Ceci pour tout le composant AllEvents. C'est fonctionnel, çà a un beau rendu, c'est du joomla pour du joomla... Maintenant je recherche les bonnes pratiques de mise à jour des doc...

Voici ce que çà donne : http://marknotes.allevents3.com/ toute la partie dans le repertoire AllEvents est générée en automatique depuis les différents fichiers de configuration du composant.

[cavo789]

Re : Votre documentation d'extension, vous le gérez comment ?

Tu as programmé un script en php qui génère automatiquement tes fichiers de documentation (au format Markdown) depuis les fichiers XML de tes programmes ? (composant/modules/plugins)

C'est topissime !

[elecoest]

Re : Votre documentation d'extension, vous le gérez comment ?

Oui c'est bien cela.
et depuis cet après midi, idem pour le fichier config.xml lié au access.xml.

Avec çà j'ai tous les paramètres. Merci aux fichiers manifest de joomla qui sont bien fait donc c'est simple d'avoir ce rendu.

[cavo789]

Re : Votre documentation d'extension, vous le gérez comment ?

Cool! Faudra promouvoir cet outil à d'autres programmeurs joomla.

[elecoest]

Re : Votre documentation d'extension, vous le gérez comment ?

pour le moment c'est expérimental mais oui pourquoi pas

[ced1870]

Re : Votre documentation d'extension, vous le gérez comment ?

salut
question intéressante, Marknotes nous interroge sur l'amélioration de nos documentations
je suis aussi en train de me creuser la tete, je suis donc cette discussion avec attention
CEd

[cavo789]

Re : Votre documentation d'extension, vous le gérez comment ?

Pour info, j'ai commencé à développer un plugin de type "content" (un peu à la Joomla). J'en ai parlé hier nuit sur mon FB.

L'idée est que marknotes génère un évènement juste avant l'affichage d'une note et transmets le contenu html de celle-ci. En interceptant cet évènement, on peut alors intervenir sur le code html (ajouter une div, remplacer une variable, exécuter du code php pour injecter le résultat dans le code (p.ex. lire un fichier externe), etc.)

Affaire à suivre.

[elecoest]

Re : Votre documentation d'extension, vous le gérez comment ?

le plugin content c'est très simple.
EDIT : très simple car on a l'URL de la note.

Le top serait d'hériter du css du site joomla et que le contenu de la note MD soit repris à l'exception de la TOC.

Perso Ced1870 je peux t'envoyer le code pour générer la documentation d'un module ;-)

[ced1870]

Re : Votre documentation d'extension, vous le gérez comment ?

ouais je veux bien tester

Le top serait d'hériter du css du site joomla et que le contenu de la note MD soit repris à l'exception de la TOC.

normalement c'est juste du html/css à modifier dans ton template Marknotes (si j'ai compris comment ça marche)

j'ai un peu discuté avec Cavo, et il a soulevé un point intéressant sur le référencement. Si tu mets toute la doc sur un sous-domaine, tu peux perdre de la valeur pour le site principal par rapport à si tu mets la doc sur le domaine principal
Sans compter la gestion entre le payant et le gratuit (j'ai des docs payantes)
J'en suis encore au stade réflexion ...

[ced1870]

Re : Votre documentation d'extension, vous le gérez comment ?

pourquoi pas un composant Joomla! qui récupérerait le buffer HTML généré par Marknotes, et l'afficherait dans la zone de contenu
ça garderait le domaine principal, ça serait bon pour le référencement, et ça garderait la charte graphique
après à voir comment lier l'arborescence du menu MN pour actualiser les pages (en Ajax ?)

c'est une idée en passant ...

[elecoest]

Re : Votre documentation d'extension, vous le gérez comment ?

on est bien en phase

Maintenant ton sous domaine tu peux aussi le définir en répertoire. Dans mon cas : www.AllEvents3.com/marknotes

je t'envoie le code sur quelle adresse ?

[ced1870]

Re : Votre documentation d'extension, vous le gérez comment ?

ah oui pas mal
petit aparté sur les css/responsive, il va falloir améliorer un peu ça car dans les deux directions ça ne s'adapte pas très bien (meme si on modifie que la hauteur de la fenetre, ça reste figé et la scrollbar ne s'affiche pas forcément ce qui empeche la lecture du contenu)
@cavo : on peut voir ça ensemble si tu as besoin d'aide sur la partie CSS

maintenant j'ai quand meme une question référencement. Les notes sont chargées en Ajax et la page ne se recharge pas (très bien pour la rapidité), mais ça ne sera pas indexé par les moteurs alors ?

(désolé si je sors un peu du sujet initial)

[cavo789]

Re : Votre documentation d'extension, vous le gérez comment ?

ah oui pas mal
petit aparté sur les css/responsive, il va falloir améliorer un peu ça car dans les deux directions ça ne s'adapte pas très bien (meme si on modifie que la hauteur de la fenetre, ça reste figé et la scrollbar ne s'affiche pas forcément ce qui empeche la lecture du contenu)
@cavo : on peut voir ça ensemble si tu as besoin d'aide sur la partie CSS

C'est un projet Open Source Cédric : récupère le dépôt sur GitHub et modifie mes fichiers puis propose un "PR" ;-)
Merci car oui, un peu d'aide côté design est plus que bienvenue.

(ai-je déjà dit que j'étais nul sur ce point-là ? :-D )

maintenant j'ai quand meme une question référencement. Les notes sont chargées en Ajax et la page ne se recharge pas (très bien pour la rapidité), mais ça ne sera pas indexé par les moteurs alors ?)

Là, c'est simple : sitemap.xml.

Référence le tonsite/marknotes/sitemap.xml et le tour est joué.

(ce fichier n'existe pas mais le routeur est assez intelligent que pour le générer à la volée)

[ced1870]

Re : Votre documentation d'extension, vous le gérez comment ?

(ai-je déjà dit que j'étais nul sur ce point-là ? :-D )

heu ... comment dire ...

je prends note pour le sitemap

Pour github, je n'ai jamais pris le temps de bien m'y pencher donc je ne l'utilise pas pour l'instant
j'ai essayé une fois, j'ai mis 1h à soumettre un truc pour lequel je n'ai jamais réussi à supprimer un espace en trop ...