Documentation

Cette documentation a été écrite pour SkyDocs v0.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.

CircleCI

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éTypeRequisDescription
project_namechaîneouiLe titre de votre documentation.
project_descriptionchaîneouiLa description de votre documentation.
project_urlchaîneouiL'adresse URL de votre documentation.
default_languagechaîneouiLa language par défaut de votre documentation.
lunr_searchbooléennonSi 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.
default_order_alphabeticalbooléennonSi 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éTypeRequisDescription
titlechaîneouiTitre de l'entée.
linkchaîneouiLien ajouté au menu.
weightentierouiUne page avec une petite weight se situera devant une autre page avec une plus grande weight.
new_tabbooléennonSi vous passez cette valeur à true, target="_blank" sera ajouté au lien.
childrenliste d'entrées de menunonContient 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 :

SyntaxeValeurs par défautDescription
java -jar SkyDocs.jar new [directory]directory : dossier courantCréé une nouvelle documentation dans le dossier spécifié.
java -jar SkyDocs.jar build [directory]directory : dossier courantGé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.
java -jar SkyDocs.jar serve [directory] [port]directory : dossier courant
port : 4444
Génère la documentation contenue dans le dossier spécifié et la sert sur localhost avec le port spécifié. Pas de minification.
java -jar SkyDocs.jar updateVérifie si des mises à jours sont disponibles.
java -jar SkyDocs.jar help [command]command : toutesAffiche une liste des commandes disponibles avec leur description.

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.

28 août 2017 12:39:54