Open Time - Mot-clé - documentation<p>Open time, open mind, open eyes</p>2024-03-28T05:07:02+01:00Franck Paulurn:md5:61070eb8c883ae7581f861faefddecbfDotclearDoc codeurn:md5:7d5909dd1c1dd3fb5354de9baed4bdba2022-09-13T08:09:00+02:002022-09-13T09:09:40+02:00FranckBrèvesdocumentationdotcleardéveloppement <p><img src="https://open-time.net/public/memojis/reflexion.jpg" alt="" style="margin: 0 auto; display: table;" height="421" width="421" /></p>
<p>En train de revoir un gros fichier, <var>inc/public/class.dc.template.php</var>, qui définit l’essentiel des balises <i lang="en">template</i> disponible dans Dotclear.</p>
<p>J’y ai trouvé de la doc au pseudo-format <a href="https://fr.wikipedia.org/wiki/Document_type_definition"><abbr title="Document type definition">dtd</abbr></a> qui décrit les attributs possibles d’icelles, doc qui servait un temps à générer automatiquement <a href="https://fr.dotclear.org/documentation/2.6/resources/templates">la documentation associée</a> sur le site Dotclear.</p>
<p><a href="https://fr.dotclear.org/documentation/2.6/resources/templates/blog#tplblogupdatedate">Exemple</a> :</p>
<pre><code class="language-php"> /*dtd
<!ELEMENT tpl:BlogUpdateDate - O -- Blog last update date -->
<!ATTLIST tpl:BlogUpdateDate
format CDATA #IMPLIED -- date format (encoded in dc:str by default if iso8601 or rfc822 not specified)
iso8601 CDATA #IMPLIED -- if set, tells that date format is ISO 8601
rfc822 CDATA #IMPLIED -- if set, tells that date format is RFC 822
>
*/
public function BlogUpdateDate($attr)
{
…
}
</code></pre>
<p>Cette documentation, sur le site Dotclear, n’a en fait pas été mise à jour depuis 2013 ; je suppose qu’à l’époque il y avait encore un outil pour la générer depuis le code source, mais je n’ai pas réussi à mettre la main dessus, ce qui n’est pas grave en soi puisqu’en fait cette documentation n’est pas accessible facilement depuis l’index de la documentation Dotclear.</p>
<p>Il en existe une autre, mise à jour au fur et à mesure, qui est disponible depuis <a href="https://fr.dotclear.org/documentation/2.0/resources/themes/tags">cette page</a>. Page accessible facilement depuis <a href="https://fr.dotclear.org/documentation/2.0/resources">l’index de la documentation des ressources</a>.</p>
<p>Du coup, deux questions :</p>
<ol>
<li><p>Est-ce qu’il ne faudrait pas virer la « vieille » doc des balises qui date de 2013, balises qui ont un peu bougé (voire beaucoup) depuis pour certaines ?</p></li>
<li><p>Est-ce qu’il est utile que je documente dans le code les attributs d’icelles (voir un exemple ci-dessous) — dit autrement est-ce que ça ne fait pas double emploi<sup id="fnref:ts1663052980.1"><a href="https://open-time.net/post/2022/09/13/Doc-code#fn:ts1663052980.1" class="footnote-ref" role="doc-noteref">1</a></sup> ?</p></li>
</ol>
<pre><code class="language-php"> /**
* tpl:BlogFeedURL [attributes] : Display blog feed URL (tpl value)
*
* attributes:
*
* type (rss2|atom) Feed type, default to "atom"
* any filters See self::getFilters()
*
* @param ArrayObject $attr The attributes
*
* @return string
*/
public function BlogFeedURL(ArrayObject $attr): string
{
…
}
</code></pre>
<div class="footnotes" role="doc-endnotes">
<hr />
<ol>
<li id="fn:ts1663052980.1" role="doc-endnote">
<p>Là c’est mon côté feignasse qui cause :-) <a href="https://open-time.net/post/2022/09/13/Doc-code#fnref:ts1663052980.1" class="footnote-backref" role="doc-backlink">↩︎</a></p>
</li>
</ol>
</div>
https://open-time.net/post/2022/09/13/Doc-code#comment-formhttps://open-time.net/feed/atom/comments/15466Doxygenurn:md5:83b821f9bd2c451c856e84b706f0e8842018-02-21T07:31:00+01:002018-02-21T07:56:03+01:00FranckDotcleardocumentationdotclear <p><a href="https://open-time.net/public/illustrations/2018/doxygen-cb-main.jpg"><img src="https://open-time.net/public/illustrations/2018/.doxygen-cb-main_u.jpg" alt="" style="display:table; margin:0 auto;" /></a></p>
<p>J’ai passé un peu de temps à configurer la génération de la documentation complète de Clearbricks, avec <a href="http://www.doxygen.nl/" hreflang="en">doxygen</a>, ce qui permet, comme Dotclear l’est déjà (mais il faut que je vérifie ça) de documenter toutes les méthodes et propriétés publiques de la librairie.</p>
<p><a href="https://open-time.net/public/illustrations/2018/doxygen-cb-detail.jpg"><img src="https://open-time.net/public/illustrations/2018/.doxygen-cb-detail_u.jpg" alt="" style="display:table; margin:0 auto;" /></a></p>
<p>Encore un truc que j’avais pas encore bien fouillé et il en ressort qu’il reste un peu de doc à écrire dans le code, même s’il en existe déjà pas mal. Doxygen est plutôt axé C, C++ mais il fait correctement le job avec du PHP, même si la documentation produite présente quelques bizarreries, finalement pas très gênantes.</p>
<p>Il y a donc un fichier de configuration nouveau, nommé <mark>.doxygen.conf</mark>, à la racine de Clearbricks, et je ferai idem pour Dotclear ; la génération de la doc, créée dans le répertoire <mark>doxygen</mark> sera effectuée avec un simple :</p>
<pre><code class="language-bash">doxygen .doxygen.conf</code></pre>
<p>Pour me simplifier la vie sur mon Mac, vu que j’ai installé la version GUI de doxygen (version 1.8.4), j’ai créé un alias côté bash :</p>
<pre><code class="language-bash">alias doxygen='/Applications/Doxygen.app/Contents/Resources/doxygen'</code></pre>
<p>Pour référence, la syntaxe servant à extraire la documentation est expliquée sur <a href="http://www.doxygen.nl/manual/docblocks.html" hreflang="en">le site de doxygen</a> et également sur <a href="http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.pkg.html" hreflang="en">le site de phpDoc </a>.</p>
<p>Il va falloir que j’évalue aussi phpDoc pour me faire une idée, sauf qu’il impose d’avoir une version de PHP supérieure ou égale à 7.0 pour tourner ; alors qu’on ne demande que la 5.5 pour Dotclear, ça me parait un peu <em>too much</em>, même si l’environnement n’est pas le même.</p>
<p>Ou alors j’attends quelques semaines de changer de mac ou d’OS pour utiliser la version 7.n de PHP vu que j’ai la flemme, ce matin, de mettre à jour mon système :-)</p>https://open-time.net/post/2018/02/21/Doxygen#comment-formhttps://open-time.net/feed/atom/comments/13703Doc ou pas doc ?urn:md5:bb52487f324f09f70a4a90195a4b8ea92017-03-18T08:10:00+01:002017-03-18T08:12:52+01:00FranckDotcleardocumentationdotclearplugin <p><a href="https://open-time.net/public/screenshots/2017/mkdocs.jpg"><img src="https://open-time.net/public/screenshots/2017/.mkdocs_u.jpg" alt="" style="display:table; margin:0 auto;" /></a></p>
<p>J’ai commencé à inclure les documentations sources à quelques plugins (Yash, Typo et sysInfo pour l’instant) et je me pose la question de savoir si c’est opportun de distribuer celles-ci dans les archives des plugins, parce qu’avec quelques copies d’écran, elles commencent à peser lourd dans la balance.</p>
<p>Par exemple, pour sysInfo, l’archive est passée de 22 Ko à 2 Mo, ce qui fait pas mal, non ?</p>
<p>Solution intermédiaire : stocker les ressources images ici et s’en servir comme pseudo-CDN au sein de la doc ?</p>
<p>La question posée autrement est : avez-vous besoin des sources de la doc <strong>dans</strong> l’archive du plugin ?</p>https://open-time.net/post/2017/03/18/Doc-ou-pas-doc#comment-formhttps://open-time.net/feed/atom/comments/13254Et une de plusurn:md5:d4d1ab830c08ded29fe414fadb82770d2017-03-13T09:44:00+01:002017-03-13T09:45:05+01:00FranckDotcleardocumentationdotclearplugin <p><a href="https://open-time.net/public/illustrations/2017/curve.jpg"><img src="https://open-time.net/public/illustrations/2017/.curve_u.jpg" alt="" style="display:table; margin:0 auto;" /></a></p>
<p>Une <a href="https://open-time.net/docs/plugins/typo" title="Documentation du plugin Typo">documentation</a> de plus, celle dédiée au plugin Typo, ça me permet de supprimer les vieilles pages de doc plus vraiment à jour ici ; et puis vu que je stocke la source de la doc avec les sources du plugin dans le même dépôt, ça me permet de la versionner aussi, cerise on ze gatal !</p>https://open-time.net/post/2017/03/13/Et-une-de-plus#comment-formhttps://open-time.net/feed/atom/comments/13248Dash ou la doc à portée d'écranurn:md5:65252f5359d4b471a47cc41f96b911492016-01-15T09:36:00+01:002016-01-15T09:38:58+01:00FranckAir du tempsbonheurs du jourdocumentationdéveloppement <p>Vu hier sur le blog de <a href="http://korben.info/toutes-vos-documentations-accessibles-offline.html">Korben</a> une appli nommée <a href="https://kapeli.com/dash" hreflang="en">Dash</a> qui permet d’avoir les docs utiles sous la main et sans avoir besoin d’une connexion, d’une part, et d’autre part, qui offre un mode <em>remote</em> si on possède un smartphone ou une tablette. Certes l’ensemble revient assez cher (tout est relatif évidemment), soit environ 30€, mais c’est rudement pratique !</p>
<p><a href="https://open-time.net/public/illustrations/2016/dash-remote.jpg"><img src="https://open-time.net/public/illustrations/2016/.dash-remote_u.jpg" alt="" style="display:block; margin:0 auto;" /></a></p>
<p>Ça s’intègre plutôt bien à votre environnement de développement et vous pouvez choisir les docs visibles, parmi toutes celles que vous aurez téléchargées, en fonction de votre occupation du moment. En ce qui me concerne, c’est du PHP, Javascript, HTML et CSS, essentiellement, mais le nombre de docs disponibles est plutôt conséquent.</p>
<p>Pour moi qui fait souvent des aller-retours entre la doc et le code, pour vérifier ou trouver des alternatives, je trouve ça cool d’avoir l’affichage correspondant sur la tablette à côté du Mac tout en gardant à l’écran le code en cours de développement.</p>https://open-time.net/post/2016/01/15/Dash-ou-la-doc-a-portee-d-ecran#comment-formhttps://open-time.net/feed/atom/comments/12667