Deployer
Si vous souhaitez mettre en ligne votre propre version des ressource, nous vous proposons d'utiliser la solution offerte par GitHub Pages. Dans les grandes lignes GitHub Pages est une solution offerte par la plateforme éponyme pour mettre en ligne le contenu d'un dépôt sous la forme d'un site web (attention : le dépôt doit être "public").
- Forker les ressources
- Ajouter un fichier .nojekyll
- Utiliser les paramètres adéquats dans la commande
sphinx-build - Configurer GitHub Pages
- Se rendre sur la page https://<username>.github.io/<reponame>/
Si vous souhaitez mettre en ligne votre version des ressources, par exemple pour la partager avec vos élèves, il convient d'abord de [forker notre dépôt (https://github.com/edunumsec2/book/wiki/Fork). Pour rappel, un fork est une copie d'un dépôt qui reste liée au dépôt d'origine ; cela signifie vous pouvez encore suivre les nouvelles mises à jour dans le dépôt d'origine et mettre à jour votre nouveau dépôt. Malgré cette liaison, le nouveau dépôt reste totalement indépendant quant à la réorganisation ou transformation des fichiers qu'il contient (si tant est que la license le permette).
À partir du moment où vous avez créé un fork de nos ressources, libre à vous d'en faire ce que vous voulez.
Jekyll est le générateur de sites statiques par défaut de GitHub Pages. Ce qui signifie que si vous suivez leur marche à suivre, vous pouvez très facilement construire un site web à partir de sources markdown etc., à partir de votre dépôt GitHub.
Néanmoins, nous utilisons dans le cadre de ce projet un autre outil de génération de sites statiques, plus puissant, qui est Sphinx. La raison principale est la liberté d'action offerte par Sphinx pour la création d'extensions.
Pour utiliser Sphinx avec GitHub Pages, il est nécessaire de créer un fichier .nojekyll à l'endroit où seront déposées les pages au format HTML résultant du build. Ce dossier informe GitHub Pages que la génération de site passera par une autre pipeline que celle offerte par Jekyll.
La dernière étape, consiste à "transformer" vos sources markdown en pages html via la commande sphinx-build. Auparavant, il convient de construire correctement le fichier de configuration conf.py, tel que décrit dans la documentation d'utilisation de Sphinx.
L'intérêt de notre dépôt d'origine est que les paramètres y sont pré-établis pour vous simplifier la vie. La seule chose à laquelle vous devrez être attentifs dans le déploiement de votre site via GitHub Pages est que le dossier dans lequel se trouve l'output du build comprenne un dossier .nokekyll. Cela correspond au paramètre dans la commande suivante sphinx-build [options] <sourcedir> <outputdir> [filenames …].
Par exemple, imaginons que vous ayez créé un dossier appelé "docs" à la racine de votre dépôt. Dans ce dossier "docs", il y aura un dossier .nojekyll qui cohabitera avec tous les fichiers .html résultant de l'output de la fonction sphinx-build. Parallèlement à ça, les sources .md à builder se trouvent dans un dossier appelé "src" à la racine du dépôt.
Le paramétrage de votre commande sphinx-build sera le suivant sphinx-build src docs, où "src" correspond aux dossier dans lequel sont contenues les sources .md et "docs" correspond à l'endroit où sont stockés les fichiers résultants du build.
La dernière étape consiste à configurer GitHub Pages dans votre dépôt.
Pour cela, vous vous rendez dans les "Settings" de votre dépôt.
Puis dans "Pages"
Et ici, vous vous assurez que la "source" pour GitHub Pages corresponde bien au dossier dans lequel sont contenus l'output du build en .html et le dossier .nojekyll.
sphinx-build sans faire exprès depuis une autre branche, le tutoriel décrit ici ne fonctionnera pas. Quand on travaille avec GitHub sur la plateforme en ligne, il arrive souvent qu'en rafraîchissant la page, la branche sélectionnée se remette par défaut sur le "master" (ou "main").
Si vous avez effectué correctement la marche à suivre, après quelques minutes, le résultat sera visible à l'adresse https://<username>.github.io/<reponame>/ où et correspondent à votre nom d'utilisateur GitHub et le nom de votre dépôt. Comme on pouvait s'y attendre.