Lors d’un récent hackathon d’entreprise, la charte de mon équipe était d’améliorer la documentation pour le SDK du plug-in Steampipe. Comme les autres composants du Tuyau de vapeur système, le plugin SDK est écrit en Go et publié sur pkg.go.dev. La version qui existait quand nous avons commencé est ici. Comme d’habitude, la documentation était un catalogue de fonctions et de types généré automatiquement. Pour expliquer comment utiliser ces fonctions et ces types, nous avons fourni conseils sur le site steampipe.io.
Notre défi de hackathon était d’intégrer ces conseils dans la documentation générée. Si vous écrivez un plugin Steampipe, votre liste de tâches ressemble à ceci :
- Définir le plugin
- Créer le point d’entrée du plugin
- Définissez votre premier tableau
- …
Ces tâches nécessitent que vous utilisiez des fonctions et des types, mais bien que les commentaires attachés à ces fonctions et types puissent améliorer la documentation générée, ils sont trop granulaires pour l’exposition de haut niveau que nous visons. À la recherche d’inspiration, développeur principal de Steampipe Kaï Daguerre a remarqué que notre page de niveau supérieur manquait de la section de présentation qu’il avait vue dans la documentation pour pgxun pilote Go pour Postgres.
Cette vue d’ensemble vient de https://github.com/jackc/pgx/blob/master/doc.goqui est un long commentaire (qui utilise Aller à la syntaxe des commentaires) suivi d’une déclaration de package.
Nous avons donc ajouté un doc.go au niveau supérieur de notre dépôt pour produire cet aperçu.
IDGÉcrire un wiki dans les commentaires Go
Nous avons utilisé le nom doc.go parce que cela semble être conventionnel, mais cela aurait pu s’appeler foo.go. Ce qui est important, c’est qu’il s’agit d’un fichier Go valide qui appartient à un package. Le package ne contient aucun code, uniquement de la documentation. Nous avons écrit des en-têtes pour créer les sections de la vue d’ensemble, et dans chaque section, nous avons décrit la tâche d’un rédacteur de plug-in à l’aide d’exemples de code narratif, en ligne, de liens internes vers des fonctions et de types, et de liens externes vers des exemples ailleurs.
La possibilité de créer des liens dans l’espace de noms du code a été une révélation. Pour décrire la tâche appelée Ajouter des fonctions d’hydratationpar exemple, nous avons écrit ceci :
# Add hydrate functions A column may be populated by a List or Get call. If a column requires data not provide by List or Get, it may define a [plugin.HydrateFunc] that makes an additional API call for each row. Add a hydrate function for a column by setting [plugin.Column.Hydrate].
La section définie par le Ajouter des fonctions d’hydratation header est une cible de lien : Ajouter des fonctions d’hydratation. Et les éléments entre crochets s’affichent sous forme de liens vers un type, plugin.HydrateFuncet à une propriété, plugin.Column.Hydrate. Cela commençait à ressembler à de l’écriture wiki !
Ce qui nous manquait encore, cependant, était la possibilité de créer de nouvelles pages wiki où nous pourrions expliquer des concepts de niveau supérieur. L’aperçu était un endroit pour le faire, mais nous voulions le réserver pour la narration du parcours de l’auteur du plugin. Où pourrions-nous discuter d’un concept comme les tables dynamiques, une fonctionnalité avancée qui permet des plugins comme CSV qui n’ont pas de schéma fixe et doivent définir des colonnes à la volée ?
Kai s’est rendu compte que non seulement nous pouvions créer de nouveaux packages de documentation uniquement pour de tels sujets, mais nous pouvions également les importer afin que leurs noms soient disponibles pour le même type de liens abrégés que nous pourrions faire avec, par exemple, [plugin.HydrateFunc]. Au plus haut niveau doc.go il a fait ceci :
package steampipe_plugin_sdk import ( "github.com/turbot/steampipe-plugin-sdk/v5/docs/dynamic_tables" ) var forceImportDynamicPlugin dynamic_tables.ForceImport
Et en /docs/dynamic_tables/doc.go il a fait ceci :
package dynamic_tables type ForceImport string
Maintenant, nous pourrions écrire une phrase dans un commentaire comme celle-ci :
/* Use [dynamic_tables] when you cannot know a table's schema in advance. */ package steampipe-plugin-sdk
Et le terme entre parenthèses liens automatiques comme n’importe quel autre nom dans l’espace de noms du code.
Si cela vous semble plus difficile que cela n’en vaut la peine, vous pouvez ignorer la gymnastique d’importation et simplement utiliser un lien externe :
/* Use [dynamic_tables] when you cannot know a table's schema in advance. [dynamic_tables]: https://pkg.go.dev/github.com/turbot/steampipe-plugin-sdk/v5/docs/dynamic_tables */ package steampipe-plugin-sdk
Quoi qu’il en soit, l’expérience de création ressemble désormais plus à un wiki. Vous pouvez créer de nouvelles pages selon vos besoins et les intégrer à la documentation hypertextuelle qui réside dans la base de code.
C’était, certes, un peu difficile d’utiliser le système Go de la manière décrite ici. La syntaxe des commentaires est de type Markdown mais, frustrant, pas Markdown ; cela dépend de nombreuses conventions de formatage implicites. Si vous suivez cette voie, vous aurez besoin d’un outil de prévisualisation local, et il n’est pas très évident que celui que vous voulez ne l’est pas godoc mais plutôt pkgsite. Si nous avions découvert la commande allez installer golang.org/x/pkgsite/cmd/[email protected] nous nous serions épargnés bien des peines.
Comment est cette programmation littéraire?
Ce n’est pas le cas ! Dans son papier éponyme Knuth a écrit:
Le praticien de la programmation littéraire peut être considéré comme un essayiste, dont la principale préoccupation est l’exposition et l’excellence du style. Un tel auteur, thésaurus en main, choisit soigneusement les noms des variables et explique ce que signifie chaque variable. Il ou elle s’efforce d’avoir un programme compréhensible parce que ses concepts ont été introduits dans un ordre qui est le meilleur pour la compréhension humaine, en utilisant un mélange de méthodes formelles et informelles qui se renforcent mutuellement.
Pour soutenir cette pratique, il a inventé un système appelé la toile dont les composants, enchevêtrement et tisser, a permis à l’auteur d’un programme de raconter son histoire dans un langage mêlant code (à l’origine, Pascal) et documentation (à l’origine, TeX) de manière narrative. Nos méthodes modernes de mélange de code et de documentation, et de génération de documents à partir de commentaires intégrés, ne ressemblent que superficiellement à la pratique de Knuth, comme l’a souligné Mark Jason Dominus dans son essai. POD n’est pas une programmation littéraire (2000).
Et pourtant, maintenant que notre exercice de hackathon m’a donné un avant-goût de ce que peut être le code-as-wiki, cela ressemble à un pas vers l’approche de narration que préconise Knuth. Rappelons qu’il nomma son système la toile avant il y avait le web que nous habitons maintenant, sans parler des wikis ! Je ne peux pas prétendre que nous sommes maintenant des programmeurs lettrés au sens knuthien, et je me suis toujours demandé si seul un esprit knuthien pouvait mettre en œuvre cette vision originale. Mais cette façon d’améliorer la qualité narrative des documents générés automatiquement semble être un pas dans la bonne direction.