Refonte de la documentation MDwiki

[loup-brun]

Choisir une pile technique pour la documentation, qui ne devrait pas reposer sur du JS dans le navigateur pour être affichée.

Quelques besoins

• Documentation : la forme doit convenir en premier lieu à des contenus de documentation (et non correspondre à l’organisation visuelle/hiérarchique d’un blogue ou d’un magazine par exemple).
• i18n : prise en charge de contenus multilingues (fr / en).
• HTML-first : solution qui ne requiert pas de JavaScript pour l’affichage de documents (🚫SPA).
• Markdown : Prise en charge facile du Markdown.
• API : Possible de brancher des API tierces (par exemple, l’éventualité de connecter la documentation à la plateforme Stylo pour y gérer les contenus à même la plateforme).
• Pérennité de l’outillage : pile technique facilement reproductible (éviter les solutions reposant sur un grand nombre de dépendances, des technologies mal documentées, idiosyncrasiques qui imposent des structures non standard).

Pistes

• Hugo : générateur de site statique polyvalent avec plein de fonctionnalités, notamment une très bonne prise en charge le multilinguisme. Plusieurs thèmes existent déjà, mais une modification des thèmes sera presque certainement nécessaire, et le langage de templating de Hugo (Go HTML Templates) est un obstacle significatif qui nécessite un apprentissage non négligeable. Il n’y a pas de solution toute faite pour tirer des contenus d’une API, tout doit reposer dans les fichiers markdown du projet.
• Eleventy : générateur de site statique hybride, très configurable, écrit en JavaScript, avec accès à un très très large écosystème (plugins, bibliothèques tierces, etc.). Il n’existe pas autant de thèmes préfabriqués que pour Hugo ou Jekyll par exemple, car c’est un système relativement récent.
• Executable Books, dont MyST : écosystème JavaScript ou Python, pour produire des articles ou des livres (collections d’articles) à partir d’une vision de production de documents scientifiques.

[ggrossetie]

Je vote pour Eleventy qui est très flexible et configurable. Je l'ai utilisé pour créer https://asciidoc.org/ et c'était top 👍🏻

[antoinentl]

Liste de choses à faire (dans l'ordre) :

• mettre en place 11ty @loup-brun
• configurer des templates (menus/page d'accueil/pages de documentation/pages statiques) @loup-brun @giuliaferretti12
• configurer le multilinguisme @loup-brun
• créer un thème/graphisme (inspiration : https://spacebook.app/) @loup-brun
• création des contenus de la page d'accueil (voir pad en privé) @giuliaferretti12
• configurer markdown-it-biblatex (https://github.com/arothuis/markdown-it-biblatex/) pour les pages qui listent les publications autour de Stylo @loup-brun
• en option : créer un blog/journal (pour tester : créer des entrées pour les releases les plus récentes) @antoinentl @giuliaferretti12
• configurer l'hébergement et le déploiement
• demander un sous-domaine doc.stylo.huma-num.fr @antoinentl

Quelques détails :

• redirections : avec une page HTML et une balise meta qui renvoie depuis /fr_FR vers /fr par exemple
• hébergement : décider si on conserve GitHub Pages (autres options : serveur du labo, serveur d'Huma-Num)
• par la suite : prévoir une section sur certaines pages pour des usages plus avancées (édition du YAML, commandes LaTeX)

[thom4parisot]

@antoinentl y'a moyen de faire fonctionner stylo.huma-num.fr/docs sans que ça soit servi par l'application Stylo. Des fois que ça vous fasse moins de boulot.

[antoinentl]

Merci @thom4parisot pour la précision ! A priori on partait plutôt sur doc.stylo.huma-num.fr pour servir la documentation, notamment pour se laisser la souplesse d'héberger la documentation ailleurs.

[ggrossetie]

Cela pourrait être intéressant de (re)configurer Netlify afin d'avoir une prévisualisation des changements qui impactent la documentation: https://docs.netlify.com/configure-builds/monorepos/#build-multiple-sites-from-a-monorepo

[thom4parisot]

Merci @thom4parisot pour la précision ! A priori on partait plutôt sur doc.stylo.huma-num.fr pour servir la documentation, notamment pour se laisser la souplesse d'héberger la documentation ailleurs.

C'est aussi possible avec un répertoire, via un mécanisme de reverse proxy. C'est le mécanisme actuellement employé pour que stylo.huma-num.fr/api pointe vers un serveur Node.js local (127.0.0.1:3030). Et ça fonctionne avec une origine distante (par exemple, une adresse GitHub Pages).

stylo/infrastructure/files/stylo.huma-num.fr.conf

Line 65 in 0fa84e7

proxy_pass http://graphql_stylo;

[loup-brun]

Inspiration

Read The Docs (exemple)

---

Zotero web (avec les colonnes)

---

Docusaurus clair/sombre (exemple)

[loup-brun]

• Suite au merge Refonte de la documentation (avec Eleventy) #858, il reste à configurer le DNS stylo-doc.ecrituresnumeriques.ca pour pointer vers Netlify. @loup-brun
• Du côté de Netlify, il faudrait lier le domaine avec le projet (c'était déja fait pour les previews, comme on pouvait tester dans le fil de la PR Refonte de la documentation (avec Eleventy) #858). @ggrossetie

EDIT voir commentaire suivant ainsi que PR #926

[loup-brun]

Autre option : utiliser GH Pages pour construire le site 11ty. Ainsi, Netlify n'est utilisé qu'en preview et rien à modifier de la part de @ggrossetie, et pas besoin de changer les DNS non plus.

[ggrossetie]

Je viens de voir que c'est live! C'est beau 😍
Petit détail, je constate une double scrollbar sur Chrome/Windows :

[ggrossetie]

Si on peut avoir https://doc.stylo.huma-num.fr ça serait pas mal

[loup-brun]

Je viens de voir que c'est live! C'est beau 😍 Petit détail, je constate une double scrollbar sur Chrome/Windows :

Hourra, les double scrollbars... la marque Stylo n'est pas belle non plus sur windows, avec le petit triangle presque détaché...

[ggrossetie]

Apparemment c'est spécifique à Chrome/Edge, sur Firefox ça s'affiche bien 😅

[loup-brun]

Je vais tester, on ouvre une issue pour ça?