diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6d511215d..8d739e6d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -136,7 +136,7 @@ Le DSFR utilise Sass pour la génération automatique des styles liés à chaque Les fichiers à la racine du composant importent les éléments nécessaires depuis le dossier style. Ceux-ci étant des points d'entrée principaux, ils n'ont pas d'underscore et ne contiennent que des `@import`, pas de déclaration. - - index.scss : Fichier permettant de donner accès aux mixins, fonctions et settings du composant. Les fichiers importés ne continnent pas de déclaration directe et par conséquent il ne produit pas de code. Il importe également les index des dépendances. + - index.scss : Fichier permettant de donner accès aux mixins, fonctions et settings du composant. Les fichiers importés ne contiennent pas de déclaration directe et par conséquent il ne produit pas de code. Il importe également les index des dépendances. - main.scss : Fichier principal du composant servant d'entrée, il produit l'essentiel du code du composant. Il importe le fichier index ainsi que des fichiers modules du composant - legacy.scss : Permet de générer un fichier séparé pour le support navigateur @@ -148,7 +148,7 @@ Dans le dossier style, on retrouve les fichiers suivants lorsqu'ils s'avèrent p - _function.scss : Contient les `functions` pouvant être utilisés par le composant - _tool.scss : Contient les `mixins` pouvant être utilisées par le composant -Afin de limiter la longeur des fichiers de code (maximum une centaine de ligne), ces fichiers peuvent être redécomposer en sous fichiers qui prendront place dans des sous-dossier du même nom. +Afin de limiter la longueur des fichiers de code (maximum une centaine de ligne), ces fichiers peuvent être découpés en sous fichiers qui prendront place dans des sous-dossier du même nom. ### Javascript @@ -173,12 +173,12 @@ Certains packages font utilisation de javascript, afin d'apporter une couche int `main.js` : importe l'index et permet l'initialisation du composant. -Un dossier `script` qui contient un dossier par fonctionalité js, ici `navigation` puis : +Un dossier `script` qui contient un dossier par fonctionnalité js, ici `navigation` puis : `navigation.js` (ou nom-classe.js) contient le code de la fonctionnalité js, structurée en classes instanciables (es6) . Lors du `yarn release`, le javascript est compilé en version "module" (es6) et "nomodule" (es5), ainsi qu'en version .min et .map. -En mode développement, `yarn build` permet de regénérer uniquement la version .module.js (es6 non minifié) +En mode développement, `yarn build` permet de générer uniquement la version .module.js (es6 non minifié) ### EJS Nous utilisons au sein du DSFR, le langage de template EJS ([documentation officielle](https://ejs.co/#docs)), permettant la génération des pages d'exemples au format HTML, ainsi que les snippets de code de manière automatisée. @@ -196,12 +196,12 @@ Les fichiers ejs sont séparés dans 2 dossiers, par exemple pour le package `ca ``` Dans le dossier `example`, -`ìndex.ejs` est la page d'exemple publiée, elle affiche les différents exemples grâce à la fonction `sample()` (qui inclut l'exemple et le snippet de code) +`index.ejs` est la page d'exemple publiée, elle affiche les différents exemples grâce à la fonction `sample()` (qui inclut l'exemple et le snippet de code) Le dossier `samples` contient les différents types d'examples (inclusion des templates avec des données d'exemples) Dans le dossier `templates`, on insère ici les templates dans un sous-dossier nommé en fonction du système de templating utilisé (`ejs` pour l'instant). Ces templates sont paramétrables pour y injecter des données. Chaque fichier possède une documentation sommaire détaillant ces paramètres. -Pour accèder aux fonctions du core (comme `includeClasses()` et `includeAttr()`), chaque template inclut l'`index.ejs` de core au début du fichier : ```<% eval(include('../../../core/index.ejs')); %>``` +Pour accéder aux fonctions du core (comme `includeClasses()` et `includeAttr()`), chaque template inclut l'`index.ejs` de core au début du fichier : ```<% eval(include('../../../core/index.ejs')); %>``` La commande `yarn release` permet de générer toutes les page d'exemple. Plus spécifiquement avec la commande `yarn build`, le paramètre `-h` permet de reconstruire uniquement l'html : `yarn build -h [-p idPackage]`, avec `-p` pour préciser le(s) package(s). @@ -215,7 +215,7 @@ git checkout -b prefixe/ma-branche dev ``` ##### Nommage des branches -Afin d'organiser et d'identifier rapidement la nature du contenu des branches, il est nécessaire de prefixer les branches : +Afin d'organiser et d'identifier rapidement la nature du contenu des branches, il est nécessaire de préfixer les branches : feature/nom-de-la-branche pour les nouvelles fonctionnalités ou nouveaux composants. fix/nom-de-la-branche pour les correctifs apportés sur des fonctionnalités ou composants existants. @@ -238,7 +238,7 @@ Les valeurs possibles pour le `type` de commit sont : * **BREAKING CHANGE**: Un commit avec un footer `BREAKING CHANGE:` introduit un changement important dans le code ([[MAJOR]](https://semver.org/#summary)) -Les messages de commits sont écrits en français (exeption faite des mots réservés par conventional commit, ainsi que les termes techniques). +Les messages de commits sont écrits en français (exception faite des mots réservés par conventional commit, ainsi que les termes techniques). Exemple de commit simple : @@ -284,9 +284,10 @@ La pull request doit être faite depuis la branche de votre fork vers la branche ## Compilation -La compilation des sources permet de créer un dossier `dist`, `exemple` et `.config` à la racine du projet. Le dossier `dist` contient les fichiers CSS et JS compilés, ainsi que les favicons et l'ensemble des fonts utilisées au sein du DSFR. +La compilation des sources permet de créer un dossier `dist`, `exemple` et `.config` à la racine du projet. Le dossier `dist` contient les fichiers CSS et JS compilés, ainsi que les favicons et l'ensemble des fonts et icônes utilisées au sein du DSFR. -Le dossier `.config` contient les variables générales JS et SCSS ainsi que la configuration nécessaire au build. Plus particulièrement le fichier `config.json` répertorie toute l’arborescence de src, les dépendances et leur ordre qu’il récupère depuis les fichiers `package.yml` de chaque package et `folder.yml` pour les dossier (src, component, page, pattern) +Le dossier `.config` contient les variables générales JS et SCSS ainsi que la configuration nécessaire au build. Plus particulièrement, le fichier `config.json` répertorie toute l’arborescence de src, les dépendances et leur ordre qu’il récupère depuis les fichiers `package.yml` de chaque package et `folder.yml` pour les dossier (src, component, page, pattern). +Les fichiers `icon.scss` et `icon.json` définissent les variables d'icônes pour la génération des classes utilitaires. Le dossier `example` contient les exemples HTML générés depuis les samples ejs. L'ordre des imports css et js est défini par l'ordre des dépendances dans le `package.yml`. @@ -300,7 +301,7 @@ En mode développement, il est possible d'utiliser la commande : ``` yarn build ``` -Cette commande permet de générer uniquement les fichiers css/js/html. Cette commande est plus rapide puisqu'elle n'éxécute pas les test, et ne compile pas les fichier .map, .md, .min.css, .nomodule.js... +Cette commande permet de générer uniquement les fichiers css/js/html. Cette commande est plus rapide puisqu'elle n'exécute pas les test, et ne compile pas les fichier .map, .md, .min.css, .nomodule.js... De plus, grâce au paramètre `-p` il est possible de spécifier uniquement les packages que l'on souhaite recompiler. Pour voir les différents paramètres disponibles : `yarn build --help` @@ -308,12 +309,19 @@ Pour voir les différents paramètres disponibles : `yarn build --help` ## Autres commandes ### Icônes -La gestion des icônes se fait à l'aide d'une webfont, chargée directement via CSS en base64. Celle-ci est générée automatiquement à partir des fichiers `.svg` se trouvant dans le dossier `src/core/icon/svg/`. Il est donc possible d'ajouter des icônes, en ajoutant des fichiers `.svg` à ce dossier, et en relançant le build : +Les icônes, placées dans le répertoire `src/core/icon/`, sont exportées à la compilation dans dist/icons et des classes utilitaires CSS sont créées dans dist/utility/icons. +Il est possible d'ajouter des icônes, en ajoutant des fichiers `.svg` dans `src/core/icon`, et en relançant le build : ``` yarn build --clean ``` +NB : Un fichier icon.scss (et icon.json) est généré dans .config à la compilation. +Il définit pour chaque icône : +- son nom, défini par le nom de l’icone +- sa catégorie, défini par son dossier +- sa famille (dsfr ou remix), par défaut remix, dsfr si le nom de l’icone est préfixé par “fr--” +- son chemin d’accès ### Sassdoc Des commentaires spéciaux sont utilisés sur l'ensemble des fichier `scss`, afin de permettre la génération d'une [Sassdoc](http://sassdoc.com/) automatiquement, documentant l'ensemble des `mixins` et `functions` utilisés sur le DSFR : @@ -325,7 +333,7 @@ Cette commande permet la génération de la doc dans le dossier `sassdoc`, à la ### Tests Afin de s'assurer de la qualité du code, nous utilisons des tests automatisés qu'il est nécessaire d'exécuter régulièrement pour vérifier que le code du DSFR reste valide et cohérent, notamment avant d'effectuer des pull requests sur le repository de production, et avant publication sur NPM. -Ces tests sont éxecutés lors de la commande : `yarn release` +Ces tests sont exécutés lors de la commande : `yarn release` Ou plus spécifiquement avec : ``` diff --git a/README.md b/README.md index 9c4fb0e6b..508b86813 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Il est possible de télécharger l'ensemble du **DSFR** au format zip ci-dessous [Fichiers statiques](https://gouvfr.atlassian.net/wiki/spaces/DB/pages/223019574/D+veloppeurs#Fichiers-statiques) ### NPM -Le **DSFR** est disponible sur NPM via un ensemble de packages qu'il est possible d'ajouter directement à votre projet. Il est de ce fait nécessaire d'installer [NodeJS](https://nodejs.org), et d'avoir un fichier **package.json** à la racine de votre projet. (Il est possible d'en créer un directement via la commande ```npm init```). +Le **DSFR** est disponible sur NPM via un ensemble de packages qu'il est possible d'ajouter directement à votre projet. Il est de ce fait nécessaire d'installer [NodeJS](https://nodejs.org), et d'avoir un fichier **package.json** à la racine de votre projet. (Il est possible d'en créer un directement via la commande `npm init`). Une fois en place, il suffit d'installer le package **@gouvfr/dsfr** contenant l’ensemble des composants: @@ -26,7 +26,7 @@ yarn add @gouvfr/dsfr Une fois terminé le dsfr sera alors installé dans le dossier ```node_modules/@gouvfr/dsfr/```. -Pour visualiser les exemples, il est nécéssaire de lancer un serveur local : +Pour visualiser les exemples, il est nécessaire de lancer un serveur local : ``` @@ -48,13 +48,15 @@ Une structure minimale serait : ``` / Racine du projet -└── font -└── dsfr - └── dsfr.min.css - └── dsfr.module.min.js - └── dsfr.nomodule.min.js -└── favicon └── index.html +└── dsfr.min.css +└── dsfr.module.min.js +└── dsfr.nomodule.min.js +└── favicon +└── font +└── icons +└── utility + └── icons ``` Les polices de caractères utilisées sur le DS, à savoir la Marianne et la Spectral, sont des fichiers .woff et .woff2, ils doivent se trouver dans le répertoire font. Ce dossier doit être placé au même niveau que le dossier contenant le CSS du core dsfr ('dsfr' dans notre exemple puisque dsfr.min.css contient le core) @@ -70,7 +72,8 @@ Consulter la [documentation des paramètres d’affichage](https://gouvfr.atlass
- + + @@ -89,23 +92,23 @@ Consulter la [documentation des paramètres d’affichage](https://gouvfr.atlass --> - - + +