Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- RoboComp
- Rédacteur technique:
- Le Thái an
- Nom du projet:
- Composants de base de RoboComp
- Durée du projet:
- Durée standard (3 mois)
Project description
Motivation
RoboComp est l'un des frameworks de robotique les plus connus pour la recherche et les applications pratiques. Le dépôt robocomp comprend un large éventail de composants (gérés dans un plus petit dépôt appelé "robocomp-robolab") pour différentes applications de robotique telles que la commande motrice, la localisation et la cartographie, la navigation, la reconnaissance, etc. Cependant, le dépôt des composants n'inclut pas de documentation détaillée sur la compilation ou l'utilisation de chaque composant, ce qui limite la facilité d'utilisation pour les nouveaux développeurs. Cette proposition vise à résoudre ce problème en documentant les composants essentiels de RoboComp et en compilant un exemple de document d'utilisation pour combiner différents composants afin de résoudre une tâche robotique spécifique. Les détails du processus de documentation seront abordés dans la section suivante, puis suivis de la section des jalons pour planifier le délai nécessaire à la réalisation du projet. Enfin, quelques notes sur le processus de documentation sont mentionnées.
Description
Comme mentionné, ce projet a deux objectifs principaux:
- Documentez la description détaillée, la compilation et l'installation, la configuration, les utilisations et les problèmes connus concernant chaque composant de RoboComp.
- Rédige un guide d'exemple qui utilise différents composants dans un environnement RoboComp pour résoudre une tâche robotique spécifique, la localisation.
Actuellement, la plupart des composants de base du dépôt robocomp-robolab ne comportent pas d'instructions détaillées sur la compilation et l'utilisation dans différentes configurations de paramètres. Cela crée un obstacle énorme pour les nouveaux développeurs qui souhaitent utiliser des composants dans leur projet ou contribuer au framework. En effet, de nombreux composants sont des wrappers de pilotes ou de bibliothèques externes ayant de nombreuses dépendances, ce qui rend la tâche de compilation et d'installation difficile. En outre, de nombreux composants encapsulent un pilote d'appareil complexe (par exemple, hokuyoComp) afin de fournir une interface de message dans RoboComp, qui nécessite des connaissances spécifiques à l'appareil pour régler les paramètres.
Par conséquent, le besoin d'une documentation détaillée, qui comprend les descriptions des appareils, la résolution des dépendances et les utilisations, est essentiel pour la contribution open source. Un exemple de mon document de composant hokuyoComp de travail se trouve dans le lien:
https://github.com/anindex/robocomp-robolab/tree/master/components/hokuyoComp
Pour rédiger une documentation concrète et détaillée sur les composants à l'aide d'une approche descendante, il faut au moins être capable de comprendre le contenu écrit dans ce document, car l'objectif final de la documentation est de transférer les connaissances de travail aux développeurs hérités. La structure proposée pour chaque document de composant est présentée comme suit:
- Description
- Compilation et installation
- Paramètres de configuration
- Démarrer le composant (utilisations)
- Problèmes connus
Dans l'exemple, la première consiste à recueillir des informations sur les spécifications du capteur Hokuyo, à lire le code du composant pour comprendre l'image de ses fonctionnalités et à rédiger sa description. Ensuite, comprendre l'environnement RoboComp et connaître les paramètres spécifiques à l'appareil ainsi que les dépendances de la bibliothèque vous aiderait à documenter le processus de compilation, d'installation et de configuration du composant. Par exemple, la compilation de hokuyoComp nécessite l'ancien package deb liburg0-dev d'Ubuntu 14.04, mais le package deb a été supprimé de l'application PPA d'Ubuntu dans la version ultérieure. Nous devons donc contourner ce problème pour la compilation, comme indiqué dans le document. Ce processus nous permet également d'enregistrer les problèmes connus afin d'accélérer le débogage pour les nouveaux développeurs. Enfin, les utilisations du composant pour différents scénarios sont documentées afin de faciliter son intégration dans l'environnement RoboComp pour différentes tâches de robotique.
Étapes importantes
Cette section planifie un délai initial pour atteindre les objectifs mentionnés du projet. Nous sélectionnerons les documents de composants à écrire en fonction de catégories (composants d'appareil photo, composants laser, etc.). L'estimation actuelle du temps nécessaire pour compléter le document sur les composants est basée sur le temps d'exécution d'exemples de documents hokuyoComp. Le calendrier est le suivant:
1er août – 1er sept. : Engagement avec une communauté:
- Organisation d'une réunion hebdomadaire pour définir la portée du projet ainsi que les attentes des rédacteurs et des mentors.
- Approfondir vos connaissances sur le framework RoboComp
2 sept. – 2 nov. : Rédaction de documents pour chaque composant dans le dépôt robocomp-robolab, avec affinements itératifs entre mentors et rédacteurs lors de réunions (prévues pour la plupart des documents non documentés)
2 nov. – 26 nov. : rédaction d'un document général servant d'exemple pour utiliser différents composants afin de résoudre une tâche robotique.
27 nov. – 29 nov. : rapports de fin de projet.
Après GSoD 2019: j'aimerais rester en contact avec RoboComp pour continuer à améliorer et à gérer mon travail.
Remarques finales
Il est essentiel d'écrire un exemple général d'intégration de différents composants dans l'environnement RoboComp pour que les utilisateurs comprennent l'ensemble des fonctionnalités de RoboComp. Cet exemple de document sera discuté plus en détail avec les mentors afin de décider quelle tâche robotique convient en fonction de l'implémentation actuelle de RoboComp.