---
title: Contribution aux connaissances sur le Notebook
subtitle: template ateliers Journées GT Notebook
date: 2024-10-07
layout: notes
header-includes: |
<style>
body { font-family: mono;}
div.content {max-width: 800px;}
div.notes {font-size: large; }
code { font-size: 0.85em; }
figure img { border: 2px #eee solid; border-radius: 5px;}
figcaption { font-size: 1em; }
/*section.level2 {display: initial; width: 60%; border-right: 2px solid #eee; }*/
section.level2 {border: 1px #ddd solid; border-radius: 3px; flex: 1 1 500px;}
section.footnotes {display: inline-block; width: 60%; font-size: small;}
section.footnotes hr {border-bottom-width: 2px}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.info, section.info {color: #31708f; background-color: #d9edf7; border-color: #bce8f1; border: 1px solid ; padding: 0.7em 1em; margin-bottom: 0.5em;}
div.success, section.success {color: #3c763d; background-color: #dff0d8; border-color: #d6e9c6; border: 1px solid; padding: 0.7em 1em; margin-bottom: 0.5em;}
div.warning, section.warning {color: #8a6d3b; background-color: #fcf8e3; border-color: #faebcc; border: 1px solid; padding: 0.7em 1em; margin-bottom: 0.5em;}
div.danger, section.danger {color: #a94442; background-color: #f2dede; border-color: #ebccd1; border: 1px solid; padding: 0.7em 1em; margin-bottom: 0.5em;}
ul { margin: 0 0 1em; }
ol>li>a { text-decoration: underline; }
a:visited {color: #2306ad;}
.blue {color: blue;}
.div130 { width: 130%; }
code, .sourceCode { background-color: lavender;}
</style>
---
## Bienvenue!
:::info
**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 :
Pour rafraichir cette page, cliquer sur le bouton `[Refresh]` en haut à gauche de la page
Pour en savoir plus, consulter [la documentation](https://pinkmypad.net).
:::
## L'atelier
:::warning
**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
:::info
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
:::success
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](https://fr.wikipedia.org/wiki/Notebook_(programmation)) 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
:::
:::success
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](https://hackmd.io/_gstPrimQLewKvlSdn-aBQ?both), 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.
:::
:::success
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](https://gitlab.huma-num.fr/gt-notebook/nix) 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](https://hackmd.io/_gstPrimQLewKvlSdn-aBQ?both), 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](https://www.sigmajs.org/) ?
- 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
:::info
Cette section peut être utilisée librement comme espace d'organisation et de documentation pendant l'atelier.
:::
:::warning
**Participants :** _ajoutez vos noms ici_
:::
### SS Groupe 3 Améliorer le
**Ancien moteur BDC et packaging NIX :**
:::info
- Le générateur de site statique [SlipBox](https://github.com/lggruspe/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**
:::info
**Description de l'architecture**
- Le [premier dépôt](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/gt-guix-doc-channel) 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](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/fork-mkdocs-zettelkasten ) est un clone/fork du **template et plugin [MKDocs Zettelkasten](https://github.com/buvis/mkdocs-zettelkasten)**.
- Le [troisième dépôt](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs) 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](https://git-scm.com/book/fr/v2/Utilitaires-Git-Sous-modules). 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](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/gt-guix-doc-channel) contenant le channel (dépendance)
- Cloner le [troisième dépot](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs) 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 :
```shell
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](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/fork-mkdocs-zettelkasten
) 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](https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs) 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 :
```shell
export GROUP_ID=4416056
export ZOTERO_KEY=06FLQnd18f1L4v6lwjefu4Pc
```
- Enfin, tapez la commande `mkdocs build -f mkdocs.yml` puis `mkdocs serve`
:::
## Compte-rendu
:::info
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
Sign in with Wallet
Connect another wallet