Détails techniques pour ce site web

Objectifs

Afin de garantir la pérénité de ce site géré par des volontaires dont le nombre et les connaissances en informatique varient au fil des années, notre site tente de remplir les conditions suivantes :

  1. Être aussi indépendant que possible de l’hébergeur du site et des technologies utilisées par le serveur web.
    • Il est facile de trouver un hébergement gratuit ou à faible coût (WordPress, Blogger, Google Sites, Squarespace, Weebly, etc.) mais il est souvent difficile d’en changer si les conditions de cet hébergeur ne sont plus acceptables : publicités, changements de tarifs, capture de données et non respect de la vie privée, etc. Le transfert du contenu, lorsqu’il est possible, est souvent dans un format difficilement transposable ailleurs sans pertes.
    • Les pages dynamiques (PHP, Node.js, ASP, etc.) sont souvent difficiles à transférer ailleurs lorsque le nouvel environnement ne dispose pas exactement de la même version du même logiciel. Le transfert est encore plus difficile lorsque le contenu dépend d’une base de données.
  2. Permettre la publication et la mise à jour du contenu du site depuis n’importe quel type d’ordinateur (Windows, Mac, Linux) avec un strict minimum de prérequis à installer.
    • Il vaut mieux éviter certains logiciels de gestion de contenu (Drupal, Joomla, Alfresco, Django CMS, etc.) qui sont assez lourds, qui requièrent une base de données, ou qui ne fonctionnent qu’avec certaines versions de certains systèmes d’exploitation.
    • Le contenu du site de l’AP doit être dans un format qui soit facilement gérable par différents logiciels libres, afin de ne pas dépendre d’un logiciel en particulier.
  3. Faciliter l’importation et la conversion de différents types de documents.
    • Les procès-verbaux des réunions de l’AP sont enregistrés sous différents formats suivant la personne qui les rédige : différentes versions de MS Word, RTF, PDF, HTML, etc. Il est souhaitable de les convertir automatiquement ou de manière aussi simple que possible dans un format qui restera encore lisible dans plusieurs années.
  4. Fournir des liens fiables à (très) long terme.
    • Des liens vers des pages spécifiques du site de l’AP peuvent se retrouver sur d’autres sites, dans des fichiers PDF ou sur des papiers imprimés. Afin d’éviter que ces liens ne renvoient vers des pages inexistantes, une page ne devrait jamais disparaître ni être déplacée après publication. Si un renommage est indispensable, alors une redirection depuis l’ancien lien devra être assurée à long terme.

En pratique…

Pour respecter ces différents objectifs, la version actuelle de ce site est constituée de pages statiques (pas besoin de PHP, ni ASP, etc.) générées à partir de fichiers au format Markdown avec un minimum d’extensions par rapport au format de base.

Le « code source » du format Markdown est lisible comme du texte et modifiable sans aucun programme particulier. De nombreux logiciels ou sites web permettent d’écrire encore plus facilement dans ce format. Des logiciels libres tels que Pandoc, Word to Markdown ou Turndown peuvent convertir de nombreux formats de fichiers au format Markdown.

Les fichiers Markdown peuvent ensuite être convertis automatiquement en site web à l’aide de logiciels tels que Hugo, Jekyll, VuePress, Pelican, etc. La disponibilité de nombreuses alternatives permet de garantir la pérénité du contenu pour autant qu’on n’utilise pas trop d’extensions propres à un logiciel en particulier.

La version actuelle de ce site utilise Hugo.

Contributions à ce site web

Les mises à jour de ce site web comportent trois étapes :

  1. La création de nouveau contenu (p.ex. articles d’actualité) ou l’importation de documents (p.ex. PV de réunions).
    N’importe qui peut contribuer de cette manière sans devoir installer de logiciels spécifiques.
  2. L’intégration du contenu dans le code source (format Markdown) puis le test pour vérifier que la mise en page et les liens fonctionnent correctement. Si le test est concluant, les modifications sont enregistrées dans le serveur git.
    Cela demande l’utilisation de hugo, git et pandoc. Il faut aussi avoir les droits d’accès au serveur git.
  3. La publication du contenu du serveur git vers le serveur web.
    Cela demande l’utilisation de hugo, git, make, rsync et lftp. Il faut aussi avoir les droits d’accès au serveur git et au serveur FTP de l’hébergeur du site web.
C o A n u t t e e n u u r ( 1 ) A u t I e n u t r é / g G r e a s t S t i S i o H o n n G n ( i a 2 t i ) r e S S H P u b W l e i b c m a a t s i t o e n r ( 3 ) F T P W W W

Création de contenu (étape 1)

Qui est concerné ? N’importe quel volontaire (membre de l’AP ou pas) peut créer un article, un PV de réunion, ou d’autres documents à publier sur le site web de l’AP.

L’idéal est de régiger cet article directement en format Markdown pour faciliter son intégration dans le site web de l’AP, mais il est aussi possible d’utiliser d’autres formats courants tels que MS Word, PDF, RTF ou autres qui seront ensuite convertis au format Markdown.

Par exemple, les procès-verbaux des réunions sont habituellement envoyés à tous les membres effectifs de l’AP. Il vaut mieux les rédiger dans un format qu’ils pourront lire facilement, comme par exemple un fichier PDF ou Word. Ce fichier pourra ensuite être converti au format Markdown par un gestionnaire du site web.

Pour les pages créées spécifiquement pour ce site, il vaut mieux les rédiger directement en utilisant la syntaxe Markdown et les éventuelles extensions disponibles pour ce site.

info Remarque : à l’avenir, il est possible qu’un éditeur Markdown en ligne soit ajouté au site web afin de visualiser plus facilement les changements. Mais l’enregistrement des modifications devra quand même se faire via Git (étape 2 ci-dessous), ce qui n’est pas facile à intégrer dans un éditeur en ligne.

Intégration et test (étape 2)

Qui est concerné ? L’intégration de contenu dans le site web de l’AP demande quelques connaissances en développement informatique. Le « code source » du site est enregistré au format Markdown dans un serveur Git qui conserve l’historique complet de toutes les modifications. Un gestionnaire du site web doit donc pouvoir utiliser git et quelques autres logiciels.

Les logiciels suivants sont nécessaires pour travailler sur le contenu du site web de l’AP :

Le logiciel Git est souvent utilisé avec des connexions sécurisées par SSH (page Wikipedia). Les environnements de développement les plus populaires (Visual Studio, Eclipse, etc.) intègrent généralement des fonctionnalités Git et SSH, donc si on utilise un de ces environnements il n’est peut-être pas nécessaire d’installer Git et SSH séparément.

Pour les tests et la préparation avant publication, les logiciels suivants sont également utiles (pas indispensables, mais fortement conseillés) :

Tous ces logiciels sont gratuits et sont disponibles pour les systèmes d’exploitation les plus courants : Microsoft Windows, Mac OS ou Linux.

Les utilisateurs de distributions Linux basées sur Debian ou Ubuntu peuvent installer tous les logiciels nécessaires à l’aide de la commande suivante :

sudo apt install hugo git openssh-client pandoc make python3 rsync unrtf poppler-utils

Un gestionnaire qui prépare un article en vue de sa publication utilisera généralement la séquence de commandes suivantes (ou l’équivalent dans un environement de développement intégré) :

Des informations complémentaires concernant les commandes utiles sont disponibles dans les fichiers situés dans le répertoire racine du code source, tels que le fichier Makefile.

Pour les nouveaux gestionnaires : Avant de contribuer au site web de l’AP, il faut d’abord obtenir une copie du code source du site depuis le serveur Git à l’aide de la commande git clone. Actuellement, ce serveur Git n’est accessible que par une connexion sécurisée par SSH. Chaque contributeur doit générer sa propre clé publique SSH et la transmettre à R. Quinet afin d’être autorisé à accéder à ce serveur Git. Il est possible que cela change à l’avenir et que le code du site soit transféré vers un service d’hébergement Git tel que GitHub, GitLab ou autre.

Publication (étape 3)

Qui est concerné ? La publication des changements depuis le serveur Git vers le serveur web de l’AP est effectuée par le(s) webmaster(s). Un webmaster devra avoir accès au serveur Git et au serveur de l’hébergeur du site web de l’AP.

Un webmaster qui souhaite publier les dernières mises à jour utilisera généralement la séquence de commandes suivantes (ou l’équivalent dans un environement de développement intégré) :

Le fichier Makefile dans le répertoire racine du code source contient quelques explications complémentaires.

info Il est prévu que cette étape 3 change à l’avenir et que la publication soit déclenchée à la fin de l’étape 2 après le git push. Cela permettrait à n’importe quel contributeur de publier des changements sans devoir attendre une validation par un webmaster. Cette automatisation est en cours de développement.

Structure du code (git)

Le code obtenu depuis le serveur Git a la structure suivante :

 ├─.git
 │  └─...
 ├─.gitignore
 ├─Makefile
 ├─TODO.md
 ├─archetypes
 │  ├─default.md
 │  └─news.md
 ├─config.toml
 ├─content
 │  ├─_index.md
 │  ├─apropos.md
 │  ├─calendrier.md
 │  ├─contact.md
 │  ├─...
 │  ├─liens.md
 │  ├─news
 │  │  ├─_index.md
 │  │  ├─2020-09-13-nouveau-site.md
 │  │  ├─2020-09-27-ajout-pvs.md
 │  │  └─...
 │  ├─oa.md
 │  ├─presentation.md
 │  ├─reunions
 │  │  ├─_index.md
 │  │  ├─pv-2016-09-06-ca.md
 │  │  ├─pv-2016-10-18-ca.md
 │  │  └─...
 │  ├─roi.md
 │  └─...
 ├─layouts
 │  └─...
 └─...

L’essentiel du contenu se trouve dans le répertoire « content », dont les deux sous-répertoires les plus importants sont « news » pour les articles d’actualité et « reunions » (sans accent) pour les PV des réunions.

Le fichier Makefile permet d’automatiser certaines tâches.

Le fichier TODO.md contient quelques notes au sujet d’améliorations possibles pour ce site.