Refonte de la documentation MDwiki

loup-brun commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

[x] mettre en place 11ty @loup-brun
[x] configurer des templates (menus/page d'accueil/pages de documentation/pages statiques) @loup-brun @giuliaferretti12
[x] configurer le multilinguisme @loup-brun
[x] 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
[x] 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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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).

https://github.com/EcrituresNumeriques/stylo/blob/0fa84e7513d8fd3d8679b836a48b27036c10b493/infrastructure/files/stylo.huma-num.fr.conf#L65

loup-brun commented 1 year ago

Inspiration

Read The Docs (exemple)

inspiration-readthedocs

Zotero web (avec les colonnes)

layout-inspiration-zotero-web

Docusaurus clair/sombre (exemple)

inspiration-docusaurus-light

inspiration-docusaurus

loup-brun commented 1 year ago

[ ] ~~Suite au merge #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 #858). @ggrossetie~~

EDIT voir commentaire suivant ainsi que PR #926

loup-brun commented 1 year ago

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 commented 1 year ago

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

ggrossetie commented 1 year ago

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

loup-brun commented 1 year ago

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 commented 1 year ago

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

loup-brun commented 1 year ago

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

EcrituresNumeriques / stylo