Ceci est un projet proposé à des étudiants en Python. L'énoncé est volontairement long, pour apprendre à détecter l'essentiel dans un cahier des charges. C'est une compétence très utile en entreprise que de savoir prendre du recul.
Un site internet statique est un site composé uniquement de fichiers présents dans un dossier :
- des fichiers HTML,
- des fichiers CSS,
- des fichiers JavaScript,
- des images,
- des vidéos,
- …
Cela s'oppose aux sites internet dynamiques, où certains de ces fichiers sont générés à la volée par du logiciel, à partir par exemple de données dans une base de données.
Héberger un site dynamique est plus complexe que pour un site statique, il faut en effet installer le logiciel qui va générer les fichiers à la volée. Par contre, héberger un site statique est relativement simple, il suffit d'avoir un petit serveur web qui met à disposition le dossier contenant les fichiers statiques.
Github fournit un hébergement gratuit de site statique. Il suffit de créer un dépôt git avec Github, et de committer dans une branche spécifique. Votre site est alors accessible à l'adresse suivante : https://votre_login.github.io/votre_nom_de_depot/
Plus de renseignement sur :
- https://pages.github.com/
- https://www.christopheducamp.com/2013/12/21/demarrer-avec-pages-github/
- https://developer.mozilla.org/fr/docs/Apprendre/Utiliser_les_pages_GitHub
Des outils commes Apache ou Nginx permettent de rendre accessible votre site par internet ou intranet :
- https://httpd.apache.org/docs/trunk/fr/getting-started.html
- http://sametmax.com/servir-des-fichiers-statiques-avec-nginx/
- https://doc.ubuntu-fr.org/nginx
- https://nginxconfig.io/
Python vous fournit un serveur web minimaliste, par exemple pour aller sur http://localhost:8080/ et y voir le site statique dont les fichiers sont dans ./dossier_de_mon_site/.
python -m http.server 8080 --directory ./dossier_de_mon_site/
Les fichiers compris par un navigateur internet sont aux formats HTML/CSS/JavaScript. Vous n'avez peut-être pas envie de taper du HTML quand vous écrivez un blog. Il serait pratique de générer les pages web à partir d'un format textuel simple, comme le markdown (https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf ou https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet), langage utilisé pour écrire le document que vous lisez actuellement (https://raw.githubusercontent.com/vpoulailleau/site_statique/master/README.md).
Certains outils open-source le font déjà, dont certains connus et en Python :
- https://blog.getpelican.com/
- https://www.getlektor.com/
- https://www.mkdocs.org/
- https://github.com/eudicots/Cactus
- http://www.sphinx-doc.org/en/master/
- https://www.getnikola.com/
Vous allez réaliser un outil convertissant un dossier de fichiers markdown et d'images en un autre dossier contenant les fichiers d'un site statique. Du HTML sera généré à partir du markdown, et cet HTML sera mélangé avec des modèles de pages web pour générer des pages toutes conformes au même modèle (par exemple avec le même logo, le même sommaire de site internet, le même fichier CSS référencé…).
Les fichiers markdown peuvent être créés :
- avec Visual Studio Code
- avec https://github.com/ncornette/Python-Markdown-Editor
- avec https://pandao.github.io/editor.md/en.html
- avec https://dillinger.io/
- …
L'extension classiquement utilisée pour les fichiers markdown est « .md ».
Pour donner un ordre d'idée, la version la plus basique du projet peut être faite en moins de 100 lignes.
Vous allez réaliser un outil en ligne de commande pour générer les fichiers du site statique. Il prendra au moins comme paramètres :
-i ./un_dossierou--input-directory ./un_dossier: le chemin du dossier de fichiers source (contenant les fichiers markdown)-o ./un_autre_dossierou--output-directory ./un_autre_dossier: le chemin du dossier où seront mis les fichiers générés pour le site statique- si le dossier existe déjà, libre à vous de soit l'effacer, soit écrire dedans pour faire des mises à jours (cela sera expliqué dans le mode d'emploi de votre outil)
- vous pouvez choisir la convention de nommage qui vous plaît pour les fichiers générés, par exemple vous pouvez utiliser comme préfixe le nom du fichier markdown correspondant (cela sera aussi expliqué)
-t ./autre_dossierou--template-directory ./autre_dossier: éventuellement le dossier contenant des modèles de pages web à compléter-hou--help: pour afficher de l'aide pour exliquer les paramètres de la commande
Vous pouvez éventuellement ajouter des paramètres comme :
- ce que vous voulez
-kou--kikoo-lolqui ajoutera dans le texte des « kikoo », « lol », « mdr », « ptdr » ou qui répète des lettres comme dans Hellllo, et autres déformations du français (https://fr.wiktionary.org/wiki/kikoolol)-aou--achtungpour aider les allemands à lire nos blogs français. Si vous appliquez les règles décrites ici, zela aidera dafantach no zami alemand dan la prononziation de notr langue et dan la kompréhenzion de no zékri
Vous pouvez utiliser :
- sys.argv (mais je ne vous le conseille pas, https://docs.python.org/fr/3/library/sys.html#sys.argv)
- argparse (https://docs.python.org/fr/3/howto/argparse.html)
- click (https://click.palletsprojects.com/en/7.x/)
Il se peut donc que votre projet soit utilisé par exemple avec :
python3.7 generateur.py --input-directory ./dossier_markdown --output-directory ./dossier_resultat/ --achtung -kVous devez au moins convertir les syntaxes suivantes :
#, un titre de niveau 1 en<h1>##, un titre de niveau 2 en<h2>###, un titre de niveau 3 en<h3>- Convertir les listes non ordonées en
<ul>et<li> - Convertir les URL (http://quelquechose.com) en
<a href="http://quelquechose.com">http://quelquechose.com</a> *un texte*, un texte important en<em>un texte</em>
Vous pouvez faire ces conversions en utilisant au choix :
- les fonctions de base de Python pour les chaînes de caractères
- les expressions régulières (https://docs.python.org/fr/3/library/re.html)
- un package de la communauté
Vous veillerez à respecter :
- la PEP 8 : https://www.python.org/dev/peps/pep-0008/ (vous pouvez vous aider avec https://github.com/ambv/black et https://github.com/hhatto/autopep8)
- la PEP 20 : https://www.python.org/dev/peps/pep-0020/
- plus de détails sur https://vpoulailleau.wordpress.com/2018/12/04/un-code-pythonique/
Votre projet personnel Python sera posté sur Github et un lien vers le dépôt public sera fourni.
À la racine de votre dépôt git se trouvera un fichier README.md qui expliquera comment fonctionne votre projet, comment l'utiliser, quel est sa licence…
Vous pouvez faire un projet libre et open-source. Beaucoup de projets Python utilisent la license MIT ou BSD 3 clauses, ces licences sont faciles à lire et très permissives. Vous pouvez aussi utiliser une licence plus stricte comme la GPL qui impose que les versions modifiées de votre projet soient aussi open-source.
Vous pouvez lire la licence BSD 3 clauses du projet https://github.com/vpoulailleau/simplelogging à l'adresse suivante https://github.com/vpoulailleau/simplelogging/blob/master/LICENSE.
Vous pouvez faire en sorte que votre projet soit installable par la communauté Python en le diffusant sur le Python Package Index (https://pypi.org/), comme par exemple https://pypi.org/project/simplelogging/.
Pour vous aidez dans cette aventure, vous pouvez utiliser https://github.com/audreyr/cookiecutter-pypackage ou encore https://ep2015.europython.eu/conference/talks/less-known-packaging-features-and-tricks.
Il se peut que, suite à des questions reçues, l'énoncé soit mis à jour. La dernière version de l'énoncé est disponible ici : https://github.com/vpoulailleau/site_statique. Vous pouvez voir son historique sur https://github.com/vpoulailleau/site_statique/commits/master.
Il va de soi que se documenter, copier du code (dans le respect des licences), discuter avec d'autres codeurs est vivement recommandé pour progresser. Regardez comment font les autres, et faites à votre façon. Soyez capables d'expliquer ce que vous avez fait.
Pour rappel toutefois, un code sans licence est par défaut protégé par le droit d'auteur, vous n'avez donc pas le droit de le copier, sauf avec un accord de l'auteur.
Le projet est adapté à tous les niveaux, une version basique est réalisable, mais le projet peut aller jusqu'à la réalisation d'un outil open-source rendu disponible à la communauté.
Les critères d'évaluation sont les suivants :
- implication (visible entre autres par l'historique de votre dépôt git)
- respect de la PEP 8
- respect de la PEP 20
- qualité du fichier README.md
- réalisation en conformité avec les fonctionnalités de base de cette énoncé
- des points bonus si vous allez plus loin
Vous pouvez vous faire une idée en utilisant le barême suivant : https://github.com/vpoulailleau/site_statique/blob/master/checklist.md.
Bon apprentissage, et bon projet.
Commencez par mettre en place la ligne de commande qui acceptera les différents paramètres mentionnés :
- Affichage du message d'aide (argparse et click savent le générer en automatique)
- Affichage du nom des dossiers passés en paramètres de la ligne de commande
Il va falloir faire un traitement pour chaque fichier markdown présent dans le dossier contenant les fichiers markdown. Pathlib et sa méthode glob peuvent aider (cf https://vpoulailleau.wordpress.com/2019/01/15/utilisez-pathlib-plutot-quos-path-ou-glob/).
Les fichiers markdown sont des fichiers texte. Il faut les ouvrir, les lire, et générer le HTML correspondant.
Le résultat de chaque conversion est stocké dans un fichier HTML dans le dossier qui contiendra les fichiers statiques (dossier fourni par la ligne de commande).
Les premières conversions (les titres) peuvent facilement se réaliser avec la méthode replace des chaines de caractères.
Il est possible de passer par les expressions régulières, vous pouvez même vous faire aider en utilisant cursive_re présenté sur https://vpoulailleau.wordpress.com/2018/11/29/des-expressions-regulieres-lisibles/.
Le mécanisme de pages modèles le plus simple est le suivant :
- Vous créez une page HTML par défaut, et sans contenu, juste le sommaire, le logo, le chargement de CSS…
- À la place du contenu dans la page HTML, vous mettez le texte « REPLACE_ME »
- Quand vous générez une page HTML, vous ouvrez la page modèle, et vous remplacer « REPLACE_ME » par l'HTML que vous avez généré à partir du markdown
- Vous pouvez utiliser https://getbootstrap.com/ pour faire rapidement du HTML plus évolué (responsive design, menus, listes déroulantes, slide show…)
- Pour ceux qui veulent faire un mécanisme plus évolué de pages modèles, vous pouvez regarder http://jinja.pocoo.org/, https://genshi.edgewall.org/, https://www.makotemplates.org/, https://opensource.com/resources/python/template-libraries