Syntaxe de la documentation
***************************
La documentation utilise Markdown et la [syntaxe Texy |https://texy.deegee.dev/syntax] avec quelques enrichissements.
Liens
=====
Pour les liens internes, on utilise l'écriture entre crochets `[lien]`. Soit sous la forme avec barre verticale `[texte du lien |cible du lien]`, soit sous la forme abrégée `[texte du lien]` quand la cible est identique au texte (après passage en minuscules et remplacement par des tirets) :
- `[Nom de la page]` -> `<a href="/en/page-name">Nom de la page</a>`
- `[texte du lien |Nom de la page]` -> `<a href="/en/page-name">texte du lien</a>`
Nous pouvons pointer vers une autre version linguistique ou une autre section. Une section désigne une bibliothèque de Nette (par ex. `forms`, `latte`, etc.) ou une section spéciale comme `best-practices`, `quickstart`, etc. :
- `[cs:Nom de la page]` -> `<a href="/cs/page-name">Nom de la page</a>` (même section, autre langue)
- `[tracy:Nom de la page]` -> `<a href="//tracy.nette.org/en/page-name">Nom de la page</a>` (autre section, même langue)
- `[tracy:cs:Nom de la page]` -> `<a href="//tracy.nette.org/cs/page-name">Nom de la page</a>` (autre section et autre langue)
Il est également possible de viser un titre précis de la page à l'aide de `#`.
- `[#Titre]` -> `<a href="#toc-heading">Titre</a>` (titre de la page courante)
- `[Nom de la page#Titre]` -> `<a href="/en/page-name#toc-heading">Nom de la page</a>`
Lien vers la page d'accueil de la section : (`@home` est un terme spécial désignant la page d'accueil de la section)
- `[texte du lien |@home]` -> `<a href="/en/">texte du lien</a>`
- `[texte du lien |tracy:]` -> `<a href="//tracy.nette.org/en/">texte du lien</a>`
Liens vers la documentation de l'API
------------------------------------
Utilisez toujours l'écriture suivante :
- `[api:Nette\SmartObject]` -> [api:Nette\SmartObject]
- `[api:Nette\Forms\Form::setTranslator()]` -> [api:Nette\Forms\Form::setTranslator()]
- `[api:Nette\Forms\Form::$onSubmit]` -> [api:Nette\Forms\Form::$onSubmit]
- `[api:Nette\Forms\Form::Required]` -> [api:Nette\Forms\Form::Required]
N'employez les noms pleinement qualifiés qu'à la première mention. Pour les liens suivants, utilisez un nom simplifié :
- `[Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]` -> [Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]
Liens vers la documentation de PHP
----------------------------------
- `[php:substr]` -> [php:substr]
Code source
===========
Un bloc de code commence par <code>```lang</code> et se termine par <code>```</code>. Les langages pris en charge sont `php`, `latte`, `neon`, `html`, `css`, `js` et `sql`. Utilisez toujours des tabulations pour l'indentation.
```
```php
public function renderPage($id)
{
}
```
```
Vous pouvez aussi indiquer le nom du fichier avec <code>```php .{file: ArrayTest.php}</code>, et le bloc de code sera rendu ainsi :
```php .{file: ArrayTest.php}
public function renderPage($id)
{
}
```
Titres
======
Soulignez le titre principal (nom de la page) par des astérisques (`*`). Utilisez les signes égal (`=`) pour séparer les sections. Soulignez les titres d'abord par des signes égal (`=`), puis par des tirets (`-`) :
```
MVC Applications & Presenters
*****************************
...
Link Creation
=============
...
Links in Templates
------------------
...
```
Encadrés et styles
==================
Perex marqué par la classe `.[perex]` .[perex]
Note marquée par la classe `.[note]` .[note]
Astuce marquée par la classe `.[tip]` .[tip]
Avertissement marqué par la classe `.[caution]` .[caution]
Avertissement fort marqué par la classe `.[warning]` .[warning]
Numéro de version `.{data-version:2.4.10}` .{data-version:2.4.10}
Les classes s'écrivent avant la ligne à laquelle elles s'appliquent :
```
.[perex]
This is the perex.
```
Notez que des encadrés comme `.[tip]` attirent l'attention et doivent donc mettre en valeur une information importante, pas un détail secondaire. Utilisez-les avec parcimonie.
Table des matières
==================
Une table des matières (les liens dans la barre latérale de droite) est générée automatiquement pour toutes les pages dépassant 4 000 octets. Ce comportement par défaut se modifie avec la [méta-balise |#Méta-balises] `{{toc}}`. Le texte de la table est repris tel quel des titres par défaut, mais il est possible d'en afficher un autre grâce au modificateur `.{toc}`, ce qui est pratique pour les titres longs.
```
Long and Intelligent Heading .{toc: A Different Text for TOC}
=============================================================
```
Méta-balises
============
- Définir un titre de page personnalisé (dans `<title>` et le fil d'Ariane) : `{{title: Another name}}`
- Redirection : `{{redirect: pla:cs}}` - voir [#Liens]
- Forcer `{{toc}}` ou désactiver `{{toc: no}}` la table des matières automatique (encadré avec les liens vers les titres).
- Définir le menu de gauche `{{leftbar: utils:@left-menu}}` ou le désactiver `{{leftbar: no}}`.
{{priority: -1}}
Syntaxe de la documentation
La documentation utilise Markdown et la syntaxe Texy avec quelques
enrichissements.
Liens
Pour les liens internes, on utilise l'écriture entre crochets [lien]. Soit sous la forme avec barre verticale
[texte du lien |cible du lien], soit sous la forme abrégée [texte du lien] quand la cible est
identique au texte (après passage en minuscules et remplacement par des tirets) :
[Nom de la page] → <a href="/en/page-name">Nom de la page</a>
[texte du lien |Nom de la page] → <a href="/en/page-name">texte du lien</a>
Nous pouvons pointer vers une autre version linguistique ou une autre section. Une section désigne une bibliothèque de Nette
(par ex. forms, latte, etc.) ou une section spéciale comme best-practices,
quickstart, etc. :
[cs:Nom de la page] → <a href="/cs/page-name">Nom de la page</a> (même section, autre
langue)
[tracy:Nom de la page] → <a href="//tracy.nette.org/en/page-name">Nom de la page</a>
(autre section, même langue)
[tracy:cs:Nom de la page] →
<a href="//tracy.nette.org/cs/page-name">Nom de la page</a> (autre section et autre langue)
Il est également possible de viser un titre précis de la page à l'aide de #.
[#Titre] → <a href="#toc-heading">Titre</a> (titre de la page courante)
[Nom de la page#Titre] → <a href="/en/page-name#toc-heading">Nom de la page</a>
Lien vers la page d'accueil de la section : (@home est un terme spécial désignant la page d'accueil de la
section)
[texte du lien |@home] → <a href="/en/">texte du lien</a>
[texte du lien |tracy:] → <a href="//tracy.nette.org/en/">texte du lien</a>
Liens vers la documentation de l'API
Utilisez toujours l'écriture suivante :
N'employez les noms pleinement qualifiés qu'à la première mention. Pour les liens suivants, utilisez un nom
simplifié :
Liens vers la documentation de PHP
Code source
Un bloc de code commence par ```lang et se termine par ```. Les langages pris en charge sont
php, latte, neon, html, css, js et sql.
Utilisez toujours des tabulations pour l'indentation.
```php
public function renderPage($id)
{
}
```
Vous pouvez aussi indiquer le nom du fichier avec ```php .{file: ArrayTest.php}, et le bloc de code sera rendu
ainsi :
public function renderPage($id)
{
}
Titres
Soulignez le titre principal (nom de la page) par des astérisques (*). Utilisez les signes égal (=)
pour séparer les sections. Soulignez les titres d'abord par des signes égal (=), puis par des tirets
(-) :
MVC Applications & Presenters
*****************************
...
Link Creation
=============
...
Links in Templates
------------------
...
Encadrés et styles
Perex marqué par la classe .[perex]
Note marquée par la classe .[note]
Astuce marquée par la classe .[tip]
Avertissement marqué par la classe .[caution]
Avertissement fort marqué par la classe .[warning]
Numéro de version .{data-version:2.4.10}
Les classes s'écrivent avant la ligne à laquelle elles s'appliquent :
.[perex]
This is the perex.
Notez que des encadrés comme .[tip] attirent l'attention et doivent donc mettre en valeur une information
importante, pas un détail secondaire. Utilisez-les avec parcimonie.
Table des matières
Une table des matières (les liens dans la barre latérale de droite) est générée automatiquement pour toutes les pages
dépassant 4 000 octets. Ce comportement par défaut se modifie avec la méta-balise
{{toc}}. Le texte de la table est repris tel quel des titres par défaut, mais il est possible d'en afficher un autre
grâce au modificateur .{toc}, ce qui est pratique pour les titres longs.
Long and Intelligent Heading .{toc: A Different Text for TOC}
=============================================================
- Définir un titre de page personnalisé (dans
<title> et le fil d'Ariane) :
{{title: Another name}}
- Redirection :
{{redirect: pla:cs}} – voir Liens
- Forcer
{{toc}} ou désactiver {{toc: no}} la table des matières automatique (encadré avec les
liens vers les titres).
- Définir le menu de gauche
{{leftbar: utils:@left-menu}} ou le désactiver {{leftbar: no}}.