What's up, doc?
Voici un moment déjà que la documentation générale du framework Substra est en ligne sans que nous n’ayons pris le temps d’en faire un petit tour, je vous propose donc d’y jeter un coup d’œil rétrospectif ensemble !
Dans l’ordre
Comme vous le savez probablement, le logiciel open source n’est pas qu’une affaire de code publiquement accessible. C’est aussi et avant tout un projet, un lieu où se rassemblent discussions, essais et développements. Il est donc primordial de pouvoir s’y installer confortablement !
Substra, framework d’orchestration de tâches décentralisées de machine learning, est un logiciel puissant et bâti sur des briques logicielles contemporaines, mais qui n’est pas encore tout à fait simple à installer côté serveur ; il était alors indispensable d’en simplifier autant que possible la prise en main.
Plan de bataille
Notre aventure a donc tout naturellement commencé par un état des lieux des éléments de documentation déjà existants et la hiérarchisation des besoins du projet auprès de l’équipe. Il a ensuite fallu se pencher sur les solutions qui y répondraient le mieux et, enfin, s’attaquer à la structure des différentes sections de la documentation.
Constat de départ
Le premier constat à s’imposer fut assez direct : il fallait documenter la manière d’installer Substra, au moins localement, pour pouvoir commencer à utiliser le logiciel et enfin tester l’exemple de prédiction clé-en-main basé sur les données du Titanic !
Mais d’abord, il faut comprendre que Substra repose sur :
plusieurs “briques” logicielles open source,
réparties sur plusieurs dépôts publics de code,
qui utilisent plusieurs versions précises, d’où la précieuse table de compatibilité que je vais finir par me faire tatouer sur la cuisse
et qui sont déployées avec Kubernetes en reposant sur plusieurs logiciels nécessitant également des versions spécifiques
Pizzaception (source)
Reprenons, calmement, Substra est constitué de :
Hlf-k8s : l’implémentation d’Hyperledger Fabric, un framework de blockchain qui est utilisé pour le mécanisme de registre (ledger) distribué. Il contient les informations non sensibles relatives aux membres d’un réseau Substra et aux tâches d’entraînement qui y sont déployées. Ces opérations sont gérées par la partie Substra-chaincode.
Substra-backend : dans les coulisses d’un réseau Substra, les opérations “serveur” sont gérées avec Django, et plus précisément avec Django Rest Framework. Chaque organisation d’un réseau Substra doit disposer de son serveur backend, pour que les serveurs des différentes organisations d’un même réseau puissent “parler” ensemble.
Substra-frontend : l’interface web est construite avec React/Redux.
Le tout est déployé et orchestré par Kubernetes, à l’aide de :
Kubectl, version 1.16.7 et Minikube, version 1.9.2, pour la partie serveur local de démo/test (par opposition à “production”)
Helm, version 2.16.1 ou Skaffold, version 1.9.2, pour la gestion de “paquets” Kubernetes qui utilise des fichiers Charts.yaml
Note : Substra est désormais déployable à l’aide de Helm v3 !
Ainsi, lorsque l’on souhaite utiliser, par exemple, la version 0.6.0 de l’interface en ligne de commande (CLI) Substra, il faudra déployer côté serveur ce qui est indiqué dans la table de compatibilité :
Il est également possible d’installer directement ces différents programmes avec Helm en utilisant les différents “charts” publiés ici, toujours en se référant bien évidemment au tableau de compatibilité.
Tableau de compatibilité
Outils de documentation
Fonctionnalités
Objectif de départ :
“Ne pas rougir devant le site de documentation de Kubeflow” !
Après discussion avec l’équipe, nous avons retenu et privilégié certaines fonctionnalités pour notre documentation, tout en observant un principe d’amélioration en continu, parmi lesquelles :
Structure claire avec une jolie table des matières, qui reste en “sticky” sur la gauche de votre navigateur pour ne pas s’y perdre
De grandes sections comme “Getting started”, déploiement, tutos, troubleshooting, définitions, questions fréquentes, etc.
Du contenu ! Par exemple, la description d’options, etc.
Annoncer explicitement que ça risque de ne pas être simple pour les utilisateurs Windows
Des sections d’aides complètes et précises pour les utilisateurs moins aguerris (cf. Python Env)
Un mécanisme de génération d’url par paragraphe pour faciliter le référencement et le partage d’une section précise
Avoir un fil d’ariane
Avoir la possibilité de signaler un problème sur la documentation
Avoir un rendu avec coloration syntaxique pour les parties de code
Utiliser des images et des gifs pour montrer les choses
Ouvrir un salon “aide” (#help)
Avoir des badges (builds, liens, etc.)
Offrir des approches différentes selon que l’on soit développeur, data scientist ou administrateur (voir Comment trouver votre chemin dans cette documentation)
Pouvoir modifier le thème et y appliquer nos couleurs
Et encore un million d’autres fonctionnalités qui sont apparues moins prioritaires au fil de l’avancée de notre aventure
Logiciels
Après avoir évalué différentes solutions permettant de répondre au mieux à ces besoins, nous nous sommes tournés vers le logiciel open source Python Sphinx qui s’est détaché par sa grande communauté, sa myriade d’extensions et sa simplicité d’utilisation.
Il a ensuite été facile d’y ajouter des extensions pour la compatibilité avec le format Markdown, plus flexible que le reStructured Text (.rst) et pour avoir un thème contemporain (Read The Doc) ajusté à nos couleurs.
Pour l’hébergement du site, nous avons opté pour utiliser directement la Github Page qui vient avec le dépot de code dédié à la documentation. Nous avons ensuite enregistré un sous domaine de substra.ai auprès de notre super fournisseur de nom de domaine (Gandi ♥), à savoir doc.substra.ai. Le tout est ensuite assemblé par l’outil de build déjà déployé au sein des projets de l’organisation Substra Foundation : Travis.
Rédaction
Une fois ce cadre posé, nous avons donc pu nous atteler à faire un tour de la documentation déjà existante. Il a alors fallu entreprendre un travail de synthèse et de restructuration de différents contenus qui étaient distribués sur plusieurs dépôts de code et parfois dans plusieurs sous-dossiers.
Le premier objectif était donc de proposer une structure claire et efficace de l’information avec :
Overview : Présentation générale du framework et repères de navigation dans les louvoiements de la documentation
Getting Started : Tout ce qu’il faut pour bien commencer à prendre en main Substra, déboguer ses ressources et même installer la plateforme localement !
Platform Description : Cette rubrique regroupe une section sur les concepts manipulés par Substra (ex. objective, traintuple & testtuple) et une seconde qui présente l’architecture logicielle du cadriciel (framework) Substra
Specific entry points : Sous ce nom moche, vous trouverez la Foire Aux Questions et un glossaire pour y rassembler les questions récurrentes posées par les utilisateurs du logiciel (dev, admin, data scientist, curieux, aficionados de l’open source) et une liste ordonnée de notions qui traversent le projet
Contribute : Cette section rassemble le très riche guide de contribution au projet Substra ainsi que la procédure pour construire une nouvelle version de la documentation
En guise de premier bilan
Sans détour : il est possible d’installer Substra en suivant la doc !
Nice! (source)
Et pour ce qui est de l’objectif de ne pas rougir devant le site de documentation de Kubeflow : en toute objectivité, on est très contents, mais on vous laisse nous faire vos retours sur Github ou sur Slack !
Concernant les fonctionnalités qui ne sont pas encore tout à fait intégrées (voir la roadmap), nous y travaillons et restons bien évidemment ouverts pour en parler avec vous !
Difficultés
Après ce petit coup de pommade, on peut noter quelques points sur lesquels des améliorations sont possibles :
Côté logiciel :
Substra reste un logiciel compliqué à déployer, notamment du fait de sa composition (plusieurs dépôts de codes, plusieurs versions à “aligner”, plusieurs fichiers de configurations yaml peu abordables sans notions de Kubernetes), il faudra donc bien veiller à clarifier encore et toujours ce qui ne l’est pas encore assez !
Les prérequis matériels (pas facile de faire tourner Substra sur un ordinateur qui a 8Go de RAM) et multiples sources d’erreur possibles ne rendent pas la stack facile à prendre en main au début, mais il faut noter que le nouveau mode de debug local (disponible à partir de la version 0.7.* du paquet Substra) améliore grandement les premiers contacts avec le SDK Python !
Les montées de version sont souvent un moment d’angoisse…
Ce serait génial de publier certains éléments de roadmap (Notez au passage que le dépôt de la documentation rassemble un certain nombre de questions, suggestions ou demandes de fonctionnalités) !
Côté documentation :
Il reste à compiler les changelogs, les modifications apportées dans chaque versions
La roadmap n’avance pas assez vite !
Je rêve toujours d’une génération parfaitement automatique de la documentation mais le procédé n’est pas évident à contrôler de manière fiable…
Je retrouve fréquemment des liens cassés dans la doc. Je suis en train d’essayer Dr Link Check, mais vous avez des suggestions ?
[Bonus] Démo
Pour ne pas avoir à obligatoirement vous lancer un déploiement local, on vous propose désormais une démo ! C’est une petite instance Substra, hébergée chez OVH, qui vous permettra de faire vos premiers essais avec un réseau Substra distant composé de deux organisations (org-1 & org-2) ! Vous pourrez ainsi vous concentrer sur votre code, configurer les permissions d’accès à vos ressources et vous connecter aux deux nœuds Substra directement via le CLI, le SDK ou même via l’interface web pour y lancer et suivre vos tâches d’entraînement et de test !
Toutes les ressources pour cette démo se trouvent par ici :
Le guide pour vous connecter à cette instance
L’exemple Titanic implémenté dans Substra, les fake_data de son opener.py ou encore le mode debug
Les exemples de la communauté sont également d’excellentes sources d’inspiration
La doc du CLI
Celle du SDK Python
substra-tools vous servira de base à la définition de vos ressources
Et de manière générale, le site de la documentation vous fournira les éléments dont vous aurez besoin
Important : cette instance de démonstration n’a pas vocation à accueillir des données sensibles. Elle est, de plus, fréquemment remise à zéro !
Open source
Sans reprendre tous les avantages qu’il peut y avoir à contribuer à un projet open source, on peut tout de même se dire que ça permet :
de rencontrer des gens formidables !
d’apprendre, entre autres, des bouts de Linux, Kubernetes, Helm, Ingress, Docker, Python, React, Rabbit, Postgresql, Hyperledger Fabric, Git, etc.
de voir comment faire une build avec Sphinx ! Promis, c’est tout simple, il suffit de modifier les fichiers qui sont dans le dossier src et de faire make livehtml dans votre terminal préféré ! Tout est décrit ici !
Si vous avez envie de donner un coup de main, sans trop savoir par où attaquer, vous pouvez :
nous aider à trouver les typos qui traînent encore dans la doc en le reportant par ici - je sais qu’il en reste…
proposer des améliorations de traductions, poser des questions, demander des clarifications, suggérer des exemples - ça nous aide et ça aidera tout le monde !
regarder, commenter ou même créer des tickets (issues)
et même prendre un ticket - on essaie de les taguer de manière cohérente, notamment les [good-first-issue] - pour proposer une Pull Request !
Merci
Tout d’abord, nous voulions exprimer nos remerciements et notre admiration pour Owkin et ses équipes techniques qui développent de manière ouverte un tel framework d’orchestration de tâches décentralisées de Machine Learning ! Merci également à l’équipe et à la communauté Substra pour sa réactivité et sa bienveillance dans toutes les opérations qui permettent la publication de ces ressources ! Et un merci spécial à Chris d’Apricity, compagnon de plongée dans les méandres des configurations serveur !
Stay tuned & explore!
Si vous en voulez plus, vous pouvez nous rejoindre sur Slack, vous abonner à la lettre d’info, participer à un atelier Substra Open Source, un atelier Data Science Responsable et de Confiance ou explorer -et étoiler ʕᵔᴥᵔʔ- nos projets sur Github :
Crédit photographie illustration de l’article : Coffee Talk by Jean Zar, Creative Common BY-NC 2.0.