Documentation
Cette documentation a été écrite pour SkyDocs v0.7.4 Beta. N'oubliez pas de le mettre à jour (un guide est disponible ci-dessous) !
Téléchargement & installation
Voici les étapes pour télécharger et installer le logiciel.
Téléchargement
Premièrement, vous devez installer Java. Si ce n'est pas déjà fait, téléchargez-le ici et installez-le.
Maintenant vous pouvez télécharger la dernière version de SkyDocs ici. Décompressez le fichier où vous le souhaitez et c'est bon !
Builds de développement
Les builds de développement de ce projet peuvent être trouvés sur le serveur d'intégration continue fourni sur cette page. Vous pouvez télécharger la dernière build de développement ici.
Créer un nouveau projet
Pour créer un nouveau projet, allez dans le dossier de SkyDocs et exécutez la commande java -jar SkyDocs.jar new [directory].
Ceci va créer un nouveau projet dans le répertoire spécifié. Si vous ne spécifiez pas de répertoire, le dossier courant sera utilisé à la place.
Vous pouvez également créer un projet manuellement : premièrement créez un dossier et créez un fichier project.yml que vous configurerez comme vous le souhaitez (les options sont disponibles ci-dessous), puis créez un fichier menu.yml (allez voir ci-dessous pour voir comment le configurer). Vous aurez également besoin de créer un répertoire content (c'est ici que vous mettrez vos pages, images, ...). C'est tout !
Configuration
Une fois créé, vous avez besoin de configurer votre projet. Voici comment faire.
Premièrement, ouvrez le fichier project.yml, il contient toutes les informations de votre projet sous syntaxe Yaml. Voici les différentes clés ainsi que leur description :
| Clé | Type | Requis | Valeur par défault | Description |
|---|---|---|---|---|
| project_name | chaîne | non (mais conseillé) | My Documentation | Le titre de votre documentation. |
| project_description | chaîne | non (mais conseillé) | Documentation built with SkyDocs | La description de votre documentation. |
| project_url | chaîne | non (mais conseillé) | https://skydocs.skyost.eu | L'adresse URL de votre documentation. |
| default_language | chaîne | non | en | La language par défaut de votre documentation. |
| enable_lunr | booléen | non | false | Si vous passez cette valeur à true, SkyDocs va inclure une page search.html qui prend keywords comme paramètre GET. Vous devez envoyer vos mots clés à cette page, et lunr va les traiter et renvoyer la liste des pages correspondantes. |
| enable_less | boolean | non | true | Si vous passez cette valeur à true, SkyDocs va analyser et convertir les fichiers LESS. Si activé, plus vous avez de fichiers LESS, plus le temps de génération de votre projet sera long. |
| default_order_alphabetical | booléen | non | false | Si vous passez cette valeur à true, le logiciel classera les pages par ordre alphabétique (suivant leur nom de fichier). page.getPreviousPage() et page.getNextPage() retourneront les valeurs correspondantes à ce classement (si les en-têtes correspondantes ne sont pas définies). |
Maintenant, ouvrez le fichier menu.yml. Il contient quelques entrées de menu :
| Clé | Type | Requis | Description |
|---|---|---|---|
| title | chaîne | oui | Titre de l'entée. |
| link | chaîne | non | Lien ajouté au menu. |
| weight | entier | non | Une page avec une petite weight se situera devant une autre page avec une plus grande weight. |
| new_tab | booléen | non | Si vous passez cette valeur à true, target="_blank" sera ajouté au lien. |
| children | liste d'entrées de menu | non | Contient les sous-menus de cette entrée. |
Ajouter des pages
Si vous souhaitez ajouter des pages, images, vidéos, etc... allez dans le dossier content. Il est recommandé de créer un sous-dossier par langue (spar exemple si votre site web a deux langues : Anglais et Français, créez deux dossiers en et fr).
Maintenant, disons que nous voulons créer une page en anglais appelée Hello avec du contenu, par exemple :
---
title: "Hello"
language: "en"
---
# Hello
Nice website uh ?
**Warning ! This text will be BOLD.**
Les premières lignes représentent l'en-tête, vous ne pouvez mettre que deux informations ici : le titre (title) et la langue de la page (language).
Vous pouvez y entrer les paramètres que vous souhaitez. Les mots réservés sont title pour le titre, language pour la langue, previous pour la page précédente et next pour la page suivante.
N'hésitez pas à jouer avec les différentes valeurs !
Attention ! Pour un menu, vous ne pourrez spécifier qu'une langue (language).
Compiler votre documentation
Lorsque vous avez terminé de configurer votre documentation, vous êtes prêt pour la générer !
Pour générer générer automatiquement la documentation, exécutez le fichier build.bat (ou build.sh). Pour la servir sur localhost, exécutez le fichier serve.bat (ou serve.sh).
Ces fichiers sont créés lorsque vous créez une documentation avec la commande java -jar SkyDocs.jar new [directory].
Vous pouvez également manuellement construire votre documentation avec la commande : java -jar SkyDocs.jar build [directory] (si vous ne spécifiez pas le répertoire, SkyDocs va essayer de générer
le projet contenu dans le dossier courant).
Pour servir manuellement votre documentation sur localhost, exécutez cette commande : java -jar SkyDocs.jar serve [directory] [port] (si vous ne spécifiez pas le répertoire,
SkyDocs va essayer de générer le projet contenu dans le dossier courant). Le port par défaut est 4444.
Commandes
Le tableau ci-dessous liste les commandes disponibles dans SkyDocs. Vous pouvez les utiliser avec le JAR java -jar SkyDocs.jar commande <arguments> ou l'exécutable SkyDocs commande <arguments>.
| Syntaxe | Valeur par défaut | Description |
|---|---|---|
new -directory [directory] | directory : dossier courant | Créé une nouvelle documentation dans le dossier spécifié. |
build -directory [directory] | directory : dossier courant | Génère la documentation contenue dans le dossier spécifié. HTML, CSS et JS seront minifiés, le temps de compilation sera donc plus long qu'avec serve. |
serve -directory [directory] -port [port] -manualRebuild [true/false] | directory : dossier courant port : 4444 manualRebuild : true | Génère la documentation contenue dans le dossier spécifié et la sert sur localhost avec le port spécifié. Pas de minification. |
update | Vérifie si des mises à jours sont disponibles. | |
help -command [command] | command : toutes | Affiche une liste des commandes disponibles avec leur description. |
gui (ou rien) | Permet de lancer l'IHM. |
Veuillez noter que les fichiers CSS et JS seront réduits lorsque vous exécuterez la commande build. Ils ne seront pas réduits avec la commande serve.
IHM
À partir de la version v0.5, SkyDocs possède un IHM ! Comme vous pouvez le voir c'est plutôt explicite : vous pouvez ouvrir vos projets, les compiler, les servir sur le réseau, etc...
Attention ! Tout est en anglais cependant.