Changeset 75146 in spip-zone

Timestamp:

Aug 30, 2013, 9:12:02 PM (6 years ago)

Author:

marcimat@…

Message:

Du mieux je crois dans la gestion des listes. On tolère l'absence de ligne vide avant.
On essaie de corriger aussi les blocs de codes. Ça marche à peu près lorsque c'est hors d'un @tag (dans la description d'une fonction par exemple) même sans les guillements ` (mais avec une indentation.

Par contre, dans un tag, il faut les presque à tous les coups. Mais nous avons un souci maintenant avec le tag @example qui n'est finalement pas fait pour recevoir (actuellement) des exemples de code intégrés (mais pour fournir un lien vers un fichier ayant des exemples). Du coup c'est pas très pratique, d'autant qu'il casse un peu le texte qui est mis dedans en essayant de trouver une url de fichier… (ça enlève les premiers guillements ).

Location:

_galaxie_/code.spip.net/autodoc/trunk

Files:

• src/autodoc/Plugin/Core/TwigZora.php (modified) (3 diffs)
• templates/zora/inclure/descriptions/functions.twig (modified) (1 diff)

_galaxie_/code.spip.net/autodoc/trunk/src/autodoc/Plugin/Core/TwigZora.php

@@ -14 +14 @@
 use Zend\Config\Factory;
 use Zend\Config\Config;
+use dflydev\markdown\MarkdownExtraParser;
+
 
 /**
@@ -150 +152 @@
     public function getFilters()
     {
+        $parser = new MarkdownExtraParser();
+
         return array(
+            /**
+             * Surcharge du filtre fournit par twig pour corriger quelques usages
+             */
+            'markdown' => new \Twig_SimpleFilter('markdown',
+                function ($value) use ($parser) {
+
+                    $value = TwigZora::prepare_markdown($value);
+                    return $parser->transform($value);
+                }
+            ),
             /**
              * Trier des éléments d'une Collection selon une demande
@@ -392 +406 @@
             ),
         );
+    }
+
+
+
+
+
+    /**
+     * Prépare le texte au passage dans markdown
+     *
+     * - Homogénéise l'indentation du texte. On enlève l'indentation
+     *   de chaque ligne. Sauf la première ligne : en effet, phpdocumentor
+     *   effectue un trim() sur l'ensemble du texte, ce qui enlève les
+     *   espacements sur cette première ligne.
+     *
+     * - Indente le contenu intérieur d'un code (commence par ``` et fini
+     *   par ```) en sautant une ligne et en enlevant les ```
+     *
+     * @param string $texte Le texte à préparer
+     * @return string Texte modifié
+    **/
+    public static function prepare_markdown($texte) {
+
+        // pas de saut de ligne = rien à faire
+        if (false === strpos($texte, "\n")) {
+            return $texte;
+        }
+
+        // 1)
+        // on essaie de calculer le nombre d'espacements à gauche des lignes
+        // pour les enlever. Pour cela, il ne faut pas tenir compte de la
+        // première ligne, car phpdocumentor effectue un trim()
+        $texte = explode("\n", $texte);
+        $espace = 10;
+        foreach ($texte as $k => $t) {
+            if ($k) {
+                $esp = strlen($t) - strlen(ltrim($t));
+                $espace = min($espace, $esp);
+            }
+        }
+
+        // on a ici normalement l'espace minimum.
+        // on enlève cet espacement sur chaque ligne
+        if ($espace) {
+            foreach ($texte as $k => $t) {
+                if (strlen($t) - strlen(ltrim($t)) > 0) {
+                    $texte[$k] = substr($t, $espace);
+                }
+            }
+        }
+
+        // 2)
+        // A) gerer un peu les codes
+        //
+        // Le problème se pose avec les tags, pas vraiment avec
+        // une description de fonction qui peut se satisfaire d'un
+        // décallage de 4 espaces.
+        // 
+        // Cependant, dans un tag, par exemple @example, si l'on veut
+        // commencer directement par le code, cela ne fonctionne pas car
+        // on ne sait pas qu'il y a une indentation
+        //
+        // B) On gère également les listes avec * ou -
+        //
+        // Si une ligne (hors bloc de code) commence par * ou -
+        // et que la ligne précédente n'est pas vide ou n'est pas une liste
+        // alors on ajoute une ligne vide…
+        $is_code = false;
+        $new_texte = array();
+
+        foreach ($texte as $k => $t) {
+            $ligne = ltrim($t);
+
+            if (!$is_code) {
+                $debut = substr($ligne,0,3);
+                // du code qui commence ?
+                if ($debut === '```') {
+                    $is_code = true;
+                    $esp = substr($t,0,strlen($t) - strlen($ligne));
+                    $new_texte[] = "\n\n" . $esp . substr($ligne, 3);
+                }
+                // sinon… du texte
+                else {
+                    if ($k and $ligne and ($ligne[0] == '-' OR $ligne[0] == '*')
+                      and ($prev = trim($texte[$k-1]))
+                      and ($prev[0] != '-' AND $prev[0] != '*')) {
+                        $new_texte[] = ""; 
+                    }
+                    $new_texte[] = $t; 
+                }
+            }
+            // que du code… à indenter
+            else {
+                $t = '    ' . $t;
+                if (substr(rtrim($t),-3) === '```') {
+                    $new_texte[] = substr(rtrim($t),0,-3) . "\n";
+                    $is_code = false;
+                } else {
+                    $new_texte[] = $t;
+                }
+            }
+        }
+        $texte = $new_texte;
+
+        $texte = implode("\n", $texte);
+        return $texte;
     }
 

_galaxie_/code.spip.net/autodoc/trunk/templates/zora/inclure/descriptions/functions.twig

@@ -73 +73 @@
 
                                                                 {% if argument.description %}
-                                                                <div class="description">{{argument.description|raw }}</div>
+                                                                <div class="description">{{argument.description|markdown|raw }}</div>
                                                                 {% endif %}
                                                         </div><!-- .param -->