Liens vers les parties précédentes:
- Première partie - introduction, primitives graphiques nécessaires pour créer une représentation graphique du code
- Deuxième partie - implémentation d'une représentation graphique du générateur de code (fait principalement en Python), langage de micro-balisage
- Troisième partie - Nouvelles fonctionnalités graphiques
Un exemple d'un environnement prenant en charge cette représentation graphique est illustré dans l'image ci-dessous.
Environnement de support de code graphiqueLa quatrième partie de l'article se concentrera sur le soutien au processus de documentation.
Autour de la brousse
Voyons ce qui est disponible pour le développeur en termes de travail avec la documentation.
Python prend en charge les lignes de documentation pour les modules, les classes et les fonctions. C'est bien. Les commentaires sont également parfois utilisés pour la documentation.
Il existe des générateurs de documentation comme
doxygen et
sphinx . C'est aussi bien.
Cependant, parfois, vous en voulez un peu plus. Il arrive que la description d'une fonction ou d'une classe devienne trop volumineuse et que les lignes de documentation (ou commentaires) «gonflent» inutilement. Le nombre de lignes non exécutables commence à supprimer le nombre de lignes exécutables, ce qui peut rendre la lecture difficile en raison d'un code flou. Un autre problème est les différents graphiques. Vous ne pouvez pas insérer une image terminée dans le texte. Vous pouvez uniquement insérer une description du diagramme, par exemple, un
diagramme Plant UML , mais même dans ce cas, il est nécessaire de fournir un rendu, ce qui est difficile à faire directement dans le texte du programme.
La solution au problème est simple - pour enregistrer une longue description dans un fichier séparé et laisser une note dans le code indiquant que la documentation est là. Un seul fichier peut être rendu de manière appropriée au bon moment. Et la marque dans le code doit de préférence être interactive, c'est-à-dire fournir une transition vers la documentation en un seul clic de souris. En principe, le marquage dans le texte du programme peut être envisagé de manière plus large: il peut s'agir d'une URL, et d'une certaine place dans un autre fichier du texte source, et d'une image, et d'un fichier externe avec documentation.
Il est facile d'imaginer un backlink. Disons que la documentation mentionne une classe du code source d'un programme ou même un bloc de code spécifique. Dans ce cas, il serait également intéressant de fournir une transition rapide vers le morceau de code souhaité.
Nous devons considérer un autre scénario important. Supposons que pendant le développement, il y avait un désir de créer un fichier de documentation externe. Il est hautement souhaitable que la question organisationnelle - où stocker, quoi appeler, comment mettre un lien vers la documentation - soit résolue aussi automatiquement que possible afin qu'il n'y ait pas de barrière inutile qui puisse étouffer l'impulsion juste de créer de la documentation.
Une discussion séparée mérite la question du format des fichiers de documentation. Récemment, le
démarque a gagné en
popularité , malgré ses critiques (par exemple,
ici ). Supposons que github affiche automatiquement la documentation de démarque lorsque vous accédez à la page du projet, ce qui est assez pratique. Dans ce cas, vous devez suivre un accord très simple et intuitif sur la dénomination et l'emplacement du fichier. Les outils pour travailler avec le démarque sont également nombreux, donc ce format est un bon candidat.
Implémentation dans Codimension IDE
Avec le texte, l'
IDE Codimension prend en charge la représentation graphique du code. L'IDE prend également en charge le langage de balisage. Par conséquent, la tâche d'ajouter un nouvel élément graphique pour afficher les liens vers la documentation est assez simple.
Pour commencer, nous formulons les exigences pour de nouvelles fonctionnalités sous une forme compacte:
- Prise en charge du format de démarque avec rendu à la volée (affichage et modification)
- Dans la représentation graphique du code, prenez en charge un nouvel élément de documentation à l'aide du langage de balisage CML
- L'élément graphique pour la documentation devrait fonctionner en trois versions: seulement un lien vers un autre endroit; ancre uniquement pour les liens provenant d'autres endroits; et lien et ancre
- Le lien peut être une URL ou pointer vers un fichier (éventuellement avec une ligne ou un numéro d'ancrage) que l'EDI est capable d'afficher
- Prise en charge du démarquage Diagrammes Plant UML
- Prend en charge la création rapide de nouveaux fichiers de documentation et des liens vers ceux-ci pour une présentation graphique du code
- Maintenir le point de départ de la documentation de documentation pour un projet, similaire à la façon dont github le fait
Markdown et rendu
L'IDE Codimension utilise
qutepart en tant que composant de l'éditeur de texte, et qutepart, à son tour, prend en charge le démarquage dès la sortie de la boîte: la mise en évidence de la syntaxe a déjà été effectuée. Pour le rendu automatique, vous pouvez utiliser la même approche que pour les fichiers python. Le domaine principal est divisé en deux parties. À gauche, le texte de démarque et à droite, le rendu:
Modification du démarque avec rendu automatiqueLe rendu, bien sûr, se fait automatiquement. L'IDE définit une pause dans l'édition de texte et met à jour le rendu si nécessaire. Pour la vue de démarque, le côté gauche avec un éditeur de texte est supprimé.
Il était pratique d'utiliser la bibliothèque
mistune pour le
rendu , qui vous permet de convertir rapidement du texte en HTML. Le code HTML prêt est envoyé au composant QT pour affichage. La bibliothèque mistune s'est également avérée suffisamment flexible pour ajouter une reconnaissance aux descriptions des diagrammes plantUML. Le diagramme est ajouté sous forme de bloc de code avec le langage correspondant, par exemple:
Reconnaissance du diagramme PlantUMLplantUML prend en charge différents types de diagrammes. Pour
Codimension, la description du diagramme est transparente, c'est-à-dire qu'elle n'est pas analysée, mais plantUML est transmis tel quel. Par conséquent, tous les types pris en charge seront affichés dans la fenêtre. Au moment de la rédaction, plantUML supportait les balises de début / fin suivantes pour différents types de diagrammes:
- @startuml / @enduml
- @startgantt / @endgantt
- @startsalt / @endsalt
- @startmindmap / @endmindmap
- @startwbs / @endwbs
- @startditaa / @endditaa
- @startjcckit / @endjcckit
Le fichier de démarque modifiable peut contenir plusieurs diagrammes, ainsi que des images téléchargées depuis le réseau. Il arrive fréquemment que très peu de texte change et que les ressources graphiques restent inchangées. Afin de ne pas pomper la même chose à chaque fois et de ne pas régénérer les diagrammes, il était nécessaire d'implémenter un cache de ressources similaires.
À partir de la bibliothèque QT, le composant QTextBrowser qui prend en charge HTML est utilisé. Malheureusement, le dialecte HTML pris en charge est limité, de sorte que le résultat final est presque impossible à perfectionner. Peut-être que ce défaut peut être corrigé à l'avenir.
Une intervention était également requise par le traitement des clics de souris sur les liens. Certains des éléments suivants peuvent apparaître dans le lien:
- ressource externe (commence par http: // ou avec https: //)
- un fichier avec un chemin relatif de la racine du projet ou du fichier courant (pratique lorsque le répertoire du projet est déplacé dans le système de fichiers)
- fichier c chemin absolu
Et s'il s'agit d'un fichier, vous pouvez spécifier (élément facultatif) soit l'identifiant de l'ancre dans ce fichier, soit le numéro de ligne. Dans les deux cas, des informations supplémentaires sont utilisées pour faire défiler le fichier jusqu'à l'emplacement souhaité.
Élément graphique
Il est logique d'entrer un élément graphique à l'aide d'un nouveau commentaire CML, similaire à la façon dont cela a déjà été fait, par exemple, pour les groupes. CML prend en charge les attributs, qui sont également requis pour le nouvel élément graphique.
Un lien vers la documentation est à certains égards similaire à un commentaire - ce n'est pas une ligne exécutable du programme, mais fournit des informations supplémentaires sur un certain contexte.
L'IDE Codimension reconnaît plusieurs types de commentaires: indépendants, principaux et latéraux. Pour la documentation, il semble prudent de maintenir des éléments graphiques indépendants et principaux de la même manière que pour les commentaires. Il y a confusion avec l'élément latéral pour la documentation. Le point est de savoir comment les commentaires secondaires sont rendus pour un bloc de code sur plusieurs lignes. Un rectangle est dessiné à droite du bloc, couvrant toutes les lignes du commentaire latéral avec prise en charge des numéros de ligne correspondants. Et que faire si le document CML s'est réuni au milieu du commentaire latéral n'est pas entièrement clair. D'un autre côté, le lien mène toujours à un autre endroit, donc la prise en charge des documents CML latéraux semble redondante - le contexte d'une ligne particulière dans le bloc de code est très étroit. La prise en charge des documents CML latéraux pour les fonctions et les classes semble également redondante. Par conséquent, à ce stade, seuls les documents CML indépendants et de premier plan seront mis en œuvre. Il convient de noter que si à l'avenir il existe un besoin raisonnable de prendre en charge les documents CML latéraux et une bonne idée de la façon de les afficher, cette fonctionnalité peut être ajoutée.
Voyons ce qui doit être affiché dans un élément graphique. De toute évidence, vous avez besoin de texte pour l'élément. Le texte est défini par le développeur et vous indique à quoi pointe le lien. Il a été mentionné précédemment qu'il est souhaitable de fournir une transition vers la documentation en un seul clic. Le texte de l'élément graphique ne convient pas, car la continuité entre le comportement des autres éléments doit être respectée - en cliquant avec la souris, l'élément graphique est sélectionné. Cependant, la résolution du problème est simple: vous pouvez ajouter une icône, par exemple, à gauche du texte, et cliquer sur l'icône entraînera la transition.
Maintenant, la liste des attributs pour le commentaire doc CML est claire:
- lien - lien vers un autre endroit
- ancre - identifiant d'ancre pour les liens provenant d'autres endroits
- title - texte à afficher dans l'élément graphique
- bg, fg, border - couleurs individuelles de l'élément, s'il doit être mis en évidence d'une manière spéciale
Au moins un des deux attributs lien et ancre doit être présent. Sans eux, un tel commentaire de doc CML n'a pas beaucoup de sens. D'autres attributs sont facultatifs. Le texte peut ne pas être du tout et les couleurs peuvent être standard.
Voici un exemple de code utilisant le doc CML et sa représentation graphique:
Commentaires de document CML indépendants et de premier planLa différence entre les éléments de tête et les éléments indépendants est uniquement là où le connecteur mène: soit à un bloc spécifique, soit à un connecteur entre des blocs.
Lorsque le curseur de la souris se trouve sur l'icône et que l'élément a un attribut de lien, la forme du curseur change, suggérant qu'un clic sera effectué.
L'élément graphique prend également en charge le menu contextuel. Une option est disponible pour afficher ou modifier les attributs des éléments, y compris les couleurs, et l'option pour supprimer un élément.
Autres éléments graphiques
Presque tous les autres éléments de la représentation graphique du code peuvent avoir de la documentation (les exceptions, par exemple, sont les commentaires et les docstrings). Par conséquent, ils ont un moyen de créer un élément de documentation via le menu contextuel.
Menu contextuel pour travailler avec la documentationIl n'y a que deux options. Le premier "Ajouter / modifier un lien / une ancre de document ..." mène à une boîte de dialogue modale pour saisir manuellement les attributs de lien, d'ancre et de titre. Ici, le développeur a toute liberté où envoyer le lien, où placer le fichier, etc.
La deuxième option est plus intéressante. Le nom de l'élément est long, en raison des actions effectuées: "Créer un fichier doc, ajouter un lien et ouvrir pour modification". Toutes les actions sont effectuées automatiquement sans aucune saisie, ce qui vous permet de résoudre rapidement le problème organisationnel:
- Une décision est prise sur le dossier dans lequel se trouvera la documentation (nous considérerons ci-dessous)
- Dans le texte source, ajoutez
# cml 1 doc ... , qui pointe vers le fichier de documentation et contient l'ancre et le texte générés. L'ancre est générée sous la forme doc <nombre aléatoire>. Texte fixe: voir documentation - Si le fichier de documentation existe déjà, il s'ouvre pour modification dans un nouvel onglet
- Si le fichier de documentation n'existe pas, il est créé, ouvert pour modification dans un nouvel onglet, et une brève aide est ajoutée au tampon d'édition, y compris comment se référer au commentaire
# cml 1 doc ... juste inséré.
La décision concernant le fichier dépend du chargement ou non du projet. S'il est chargé, le sous-répertoire doc est créé à la racine du projet, puis le chemin d'accès relatif de la racine du projet au fichier texte source. Le nom de fichier est formé en remplaçant l'extension par .md. Par exemple, si un projet se trouve dans
/home/me/myProject
et la documentation est ajoutée pour le fichier de projet
/home/me/myProject/src/utils.py
un fichier de documentation sera créé
/home/me/myProject/doc/src/utils.md
Ainsi, la structure de la documentation du code source répète la structure du code source, et même un rapide coup d'œil au sous-répertoire doc du projet sera suffisant pour une navigation intuitive. Le schéma semble raisonnable pour le comportement par défaut, ce qui permet d'accélérer le travail avec la documentation.
Si le projet n'est pas chargé, le sous-répertoire doc est créé à côté du fichier et contient le fichier avec l'extension modifiée en .md. Un tel scénario semble cependant peu probable. Si nous parlons de documentation, il s'agit presque certainement d'un travail sur un projet, et non sur un fichier séparé.
Bien sûr, vous pouvez à tout moment modifier les éléments générés automatiquement soit en éditant
# cml 1 doc ... dans un éditeur de texte ou dans une boîte de dialogue sur une représentation graphique.
Point de départ de la documentation du projet
Pourquoi ai-je besoin d'un point de départ de documentation? À mon avis, cela peut faciliter le processus d'entrée dans le projet pour ceux qui l'ouvriront en premier. Par exemple, dans le cas d'élargir la composition de l'équipe de développement, ou pour les utilisateurs du projet. Imaginez que le projet dispose d'une documentation et qu'il se compose d'un grand nombre de fichiers. Par où commencer? Comment la documentation est-elle structurée? Au lieu de spéculer puis de les vérifier, il serait plus pratique d'avoir une indication explicite du point d'entrée recommandé.
Ici, vous pouvez étendre un peu l'approche github afin que les options d'organisation par défaut et spécifiques de la documentation fonctionnent. Si rien n'est dit, nous rechercherons le fichier README.md à la racine du projet. Et les propriétés du projet peuvent être développées avec un autre champ, qui indique un fichier spécifique du point de départ de la documentation.
Il existe deux options pour ouvrir la documentation du projet. Un bouton avec l'icône de démarque a été ajouté à la barre d'outils de la fenêtre principale IDE. Lorsque vous cliquez dessus, le fichier de documentation sera ouvert en mode visualisation, si disponible. S'il n'y a pas de fichier, l'emplacement du fichier de documentation sera proposé et un nouvel onglet s'ouvrira en mode édition avec le texte - un talon. La deuxième option est un lien vers la page d'accueil de
Codimension , qui s'affiche lorsqu'il n'y a pas d'autre onglet ouvert. Le texte d'accompagnement comprendra des mots sur la documentation du projet et un lien si la documentation est trouvée. C'est cette page d'accueil que verra l'utilisateur qui a ouvert le projet pour la première fois.
Test en pratique
La fonctionnalité décrite ci-dessus a été testée sur des chats, c'est-à-dire sur le projet de
Codimension IDE lui-même . Maintenant, le package d'installation comprend une documentation préparée au format Markdown. Ce test de fonctionnalité ne peut pas être considéré comme complètement complet, car la documentation a été préparée pour l'utilisateur final, et non par code. Cependant, l'impression générale que cela s'est avéré est tout à fait acceptable.
Questions ouvertes
Ai-je besoin de la prise en charge des éléments de documentation CML secondaires? Si oui, alors comment les dessiner, par exemple, pour un tel cas:
a = 10
On pourrait reconnaître les descriptions des diagrammes plantUML directement dans les lignes de documentation. Si un tel support est fait, alors comment afficher ces diagrammes sur la représentation graphique du code?
Pour faciliter la construction des diagrammes plantUML, on pourrait ajouter des fonctionnalités avec ce scénario:
- L'utilisateur fait un clic droit sur la classe dans la représentation graphique du code ou dans toute autre fenêtre (liste des classes de projet, contenu du fichier structuré)
- Dans le menu contextuel, sélectionne un élément pour générer une description de classe au format plantUML
- La description générée est enregistrée dans un tampon de texte.
- L'utilisateur insère du texte dans le document de démarque et le modifie si nécessaire
La vitalité d'un tel scénario est en cause, bien qu'il soit trivial de le mettre en œuvre.
Si vous avez des idées, veuillez les partager dans les commentaires.