Contribution aux connaissances sur le Notebook

cyrAmOdTQp-hr-DA3rkzXQ (edit on hackmd)

created: 2024-10-07

updated: 11:44:35 - September 28, 2025

tags:

Contribution aux connaissances sur le Notebook

template ateliers Journées GT Notebook

Bienvenue!

Bienvenue sur la page de l’atelier Contribution aux connaissances sur le Notebook !

Vous êtes invités à participer à l’édition de cette page. Il suffit d’ouvrir sa source en cliquant sur le lien edit on hackmd en haut à gauche de la page :
image

Pour rafraichir cette page, cliquer sur le bouton [Refresh] en haut à gauche de la page

Pour en savoir plus, consulter la documentation.

L’atelier

Organisation : Sébastien Rey-Coyrehourcq & membres du GTs.

Objectif·s : Comme indiqué dans la présentation des ateliers, les objectifs de ces deux ateliers sont multiples.

Vous pouvez vous rapporter aux différents objectifs directement dans la partie sous groupe.

Durée : 4h (2*2h)

Méthodes : L’atelier repose sur le principe de …

Outils & librairies : Libres …

Dépots git :

Les notes de la BDC : https://gitlab.huma-num.fr/gt-notebook/wiki
Le groupe gitlab des dépôts pour l’atelier https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks
Le moteur de la BDC : https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/fork-mkdocs-zettelkasten
La base Zotero : https://www.zotero.org/groups/4416056/gt-notebooks/library

Déroulé de l’atelier

Cette section liste les étapes de l’atelier et indique les ressources nécessaires/disponibles pour chaque étape.

Sous groupes pour les Ateliers

:pencil2: Plutôt structure et écriture de textes FR/EN
:keyboard: Plutôt structure et écriture de codes sources

SSGROUPE 1 ( :pencil2: ) Contribution à “Wikipedia” et amélioration de la base bibliographique Zotero du GT :

Objectifs :

Dans ce sous-groupe il s’agit d’initier et de structurer un travail d’écriture qui au delà de la JE. L’actuel page Wikipédia FR sur les Notebooks est courte et peu qualitative. L’objectif à terme est d’améliorer peu à peu le contenu de cette page, ce qui peut aussi nous amener à modifier d’autres pages liés à cette dernière (ex Programmation Lettré, etc.)

Le fait que nous travaillions sur Wikipédia nous amène également à retravailler la structure et le contenu de notre base bibliographique du GT. Sur ce point Raphaëlle, Manon, Sébastien peuvent être consulté pour comprendre la structure actuelle.

Quelques idées d’étapes :
- Déclaré notre intention sur Wikipédia, en suivant le procole et les guides actuels
- Désigner qui tiendra la plume pour proposer les modifications sur Wikipedia au nom du collectif GT
- Etablir un plan détaillé de la future page
- Améliorer la base de référence bibliographique dont une partie sera dédiée à cette page Wikipedia et l’autre partie à la BDC
- Répartir les tâches d’écriture, définir un calendrier de réunions

SSGROUPE 2 ( :pencil2: ) Contribution au contenu la BDC du GT Notebook et amélioration de la base bibliographique Zotero du GT :

Objectifs :

Dans ce sous-groupe il s’agit d’initier et de structurer un travail d’écriture qui au delà de la JE. Notre première tentative de PKM lancé en 2021 n’a pas eu le succès escompté, y compris auprès des membres motivés.

Après plusieurs discussions au sein d’un sous groupe dédié du GT, nous avons identifié plusieurs freins, dont le premier tient probablement de la pléthore et de la diversité d’outils que nous utilisons déjà tous au jour le jour : emacs, vi, mails, etc. Il faut donc que l’édition de cette BDC s’intègre au mieux dans nos workflows quotidien, y compris au sein du GT, sous peine d’être voué à l’échec. Ce volet là renvoie plutôt au SSGROUPE 3 “Code & outils collectifs/collaboratifs”

Une autre cause est probablement l’absence d’un plan de route plus précis pour le contenu et la structuration de cette PKM.

Quelques idées d’étapes :

  • Etablir des templates d’écriture selon les connaissances à intégrer dans la base
  • Etablir une liste d’axiome important, des noeuds plus important de part la densité des liens qu’ils ont avec les autres noeuds (ex Literate Programming)
  • Documenter le protocole à suivre (tags/catégories, nomages des fichiers, etc.) pour un ajout de document à la base Zotero
  • Verser les comptes-rendu des deux années passés dans la BDC pour sortir peu à peu le travail de HackMD.
  • réintégrer les tags dans les md avec la syntaxe proposé par le template mkdocs zettelkasten, pour le moment çà ne marche pas.

SSGROUPE 3 (:keyboard:) : Contribuer à la fabrique de la BDC

Objectifs :

En 2021, nous avions déployé une première base de connaissance, reprenant un format zettelkasten. L’idée c’était que chacun.e puis ajouter de la connaissance pour capitaliser en un seul endroit nos réflexions et notre veille autour des Notebooks. Cette base devait être reproductible, comme le reste de l’atelier en 2021.

A cette époque j’avais fait le choix de packager les différentes parties avec Nix sous la forme de Flakes.

Comme indiqué dans le précédent SSGROUPE 2, il y avait trop de frein à l’utilisation. Après plusieurs discussions au sein d’un sous groupe dédié du GT, nous avons identifié plusieurs freins, dont le premier tient probablement de la pléthore et de la diversité d’outils que nous utilisons déjà tous au jour le jour : emacs, vi, mails, etc. Il faut donc que l’édition de cette BDC s’intègre au mieux dans nos workflows du quotidien, y compris au sein du GT, sous peine d’être voué à l’échec.

Deux idée importante :
- avoir une base de markdown centrale, lisible et si possible éditable sans conflit (ex wikilink pareil partout) avec n’importe quel outil moyennant qu’on respecte un frontmatter simple (ID, tags, etc)
- couplage avec un outil qui permet un double usage synchrone et asynchrone du contenu de la BDC (type hackmd via l’API, etherpad, Stylo)

Quelques idées d’amélioration ou de correction :

  • ajout d’un graph de navigation entre les noeuds de la BDC (ex : https://hugocisneros.com/notes/, https://quartz.jzhao.xyz/) => Sigma.js ?
  • ajout d’un bouton edit aux pages, couplage système asynchrone (git) avec un outil d’écriture synchrone (hackmd, stylo, etc.) => pas évident, on a fait un peu de veille… mais si on peut se raccrocher à stylo ca serait intéressant car communauté FR.
  • tester que les fichiers générés par différents IDE courant pour l’édition de base de connaissance en markdown (emacs, vim, obsidian, logseq, etc.) sont bien gérés au niveau du frontmatter, sinon envisager des scripts de pre-traitement/post-traitement ?
  • déployer le site web généré de la BDC avec le CI Gitlab, avec Guix

Prise de note

Cette section peut être utilisée librement comme espace d’organisation et de documentation pendant l’atelier.

Participants : ajoutez vos noms ici

SS Groupe 3 Améliorer le

Ancien moteur BDC et packaging NIX :

  • Le générateur de site statique SlipBox amélioré pour l’occasion : https://gitlab.huma-num.fr/gt-notebook/nix/wiki-script
  • Une version de Pandoc plus à jour que celle de Nix : https://gitlab.huma-num.fr/gt-notebook/nix/pandoc-2-14-02
  • La mise en lien des deux packages précédents : https://gitlab.huma-num.fr/gt-notebook/nix/wiki-pandoc-nix

Nouveau moteur BDC et packaging Guix

Description de l’architecture

  • Le premier dépôt contient l’ensemble des dépendances packagés sous forme de modules pour compiler la BDC avec GUIX. Ces dépendances sont regroupés dans un channel guix qui peut être partagé avec d’autres utilisateurs ayant besoin de ces dépendances.

  • Le deuxième dépôt est un clone/fork du template et plugin MKDocs Zettelkasten.

  • Le troisième dépôt contient la définition de notre site de documentation (mkdocs.yml), utilisant le template MKDocs Zettelkasten comme theme/plugin.

    Dans ce troisième dépôt la BDC est définie comme un submodule git. Après clone du troisième dépot, le copie (liée) du dépôt qui contient les notes est dans le répertoire /docs.

Normalement vous n’avez pas besoin de toucher au premier dépôt sauf si vous ajouter une dépendance, ou une version de dépendance qui ne serais pas déjà packagé dans Guix.

Le deuxième dépôt contenant le thème/plugin Zettelkasten est celui que l’on modifiera lorsque l’on voudra ajouter des fonctionnalités au thème.

Le troisième dépôt s’appuie le plugin/thème tel qu’il est construit/tuné dans le deuxième dépôt. A ce dernier s’ajoute d’autres plugin de MkDocs :
- La reconnaissance de la bibliographie via un bibtex dans les fichiers .md est ajouté par le plugin mkdocs-bibtex
- La récupération de la base bibtex depuis zotero se fait avant compilation du site (grâce au plugin mkdocs-gen-files), via le fichier /scripts/retrieve-bib.py.

C’est aussi dans ce troisième dépôt qu’est fait le lien avec la BDC, au travers d’un submodule qui point sur un commit du dépot . Il faut intervenir manuellement pour mettre à jour ce commit en cas d’update des notes dans la BDC. Le protocole standard est cd /docs ; git pull ; cd .. ; git add /docs; git commit -m "update submodule ; git push

Installation avec Guix

  • Installer Guix sous votre Linux (ex : apt-get install guix)
  • Cloner le premier dépôt contenant le channel (dépendance)
  • Cloner le troisième dépot qui contient le moteur et un lien versla BDC : git clone --recurse-submodules https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs
  • modifier le fichier channel.scm du troisième dépot et remplacer l’url actuelle par l’url file:// actuelle du channel tel que cloné sur votre disque, puis enregistrez.
  • Executer la commande dans le répertoire : guix time-machine -C channels.scm -- shell -m manifest.scm python
  • touch notebooks.bib pour la création d’un fichier vide accueillant la biblio
  • Executez dans votre shell les deux commandes suivantes, nécessaire pour récupérer pour les fichiers bibtex de la base zotero :
export GROUP_ID=4416056
export ZOTERO_KEY=06FLQnd18f1L4v6lwjefu4Pc
  • Enfin, tapez la commande mkdocs build -f mkdocs.yml puis mkdocs serve

Installation sans Guix

  • Cloner le deuxième dépot qui contient le fork modifié du plugin/template mkdocs.
  • Installer un gestionnaire spécifique qui permet d’installer plusieurs version de python sous un même système : pyenv ou asdf par exemple.
  • Installer python 3.8 (ex avec pyenv install 3.8)
  • Installer pipenv avec votre packageur systeme : apt-get install python3-pipenv
  • Dans le répertoire du projet, lancez make update ce qui normalement devrait trouver python 3.8 et installer les dépendances requises
  • pipenv shell lance un environnement avec les dépendances installées
  • Cloner le troisieme dépot qui contient le moteur et le submodule git vers la BDC : git clone --recurse-submodules https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs
  • A ce stade il faut aussi installer les nouveaux plugins /dépendances listées dans mkdocs.yml suite aux modifications que j’ai faite dans le fork :
    • pip install mkdocs-gen-files pour lancer des scripts avant la génération du site
    • pip install mkdocs-bibtex pour la gestion de la biblio (voir /scripts)
    • pip install pyzotero pour la gestion de la biblio (voir /scripts)
    • touch notebooks.bib pour la création d’un fichier vide accueillant la biblio
    • Executez dans votre shell les deux commandes suivantes, nécessaire pour récupérer pour les fichiers bibtex de la base zotero :
export GROUP_ID=4416056
export ZOTERO_KEY=06FLQnd18f1L4v6lwjefu4Pc
  • Enfin, tapez la commande mkdocs build -f mkdocs.yml puis mkdocs serve

Compte-rendu

Cette section est utilisée comme espace de consolidation : synthèse des réalisation, difficultés/freins rencontré·e·s, pistes pour la suite, autre…

Réalisations

Difficultés rencontrées

Pour aller plus loin