Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Ignition Robotics
- Rédacteur technique:
- An Thai Le
- Nom du projet:
- Tutoriels et documentation sur l'API Ignition Physics
- Durée du projet:
- Durée standard (trois mois)
Project description
Motivation
La bibliothèque Ignition Physics permet d'utiliser de manière flexible les moteurs physiques portés vers le backend de la simulation Ignition Gazebo. De nombreux moteurs de physique externes peuvent être adaptés à la bibliothèque en tant que plug-ins composés de différents ensembles de fonctionnalités en fonction de leurs capacités et de leurs contextes d'application, afin de permettre la simulation Gazebo. Toutefois, l'état actuel de la bibliothèque ne fournit pas les éléments suivants:
- Des tutoriels complets pour créer des plug-ins physiques personnalisés qui utilisent des moteurs physiques personnalisés pour alimenter la simulation
- une documentation de l'API cohérente ;
Cette proposition vise à résoudre ces problèmes pour mieux gérer le projet et guider les nouveaux contributeurs et utilisateurs de manière plus principielle. Les détails du processus de documentation seront abordés dans la section suivante, puis suivis de la section des jalons pour planifier le calendrier de réalisation du projet. Enfin, quelques remarques sont faites sur la documentation actuelle.
Description
Ce projet a deux objectifs principaux:
- Créez des tutoriels détaillés sur la création d'un plug-in de physique personnalisé qui interagit avec l'API de la bibliothèque actuelle.
- Améliorer la documentation actuelle de l'API de la bibliothèque à des fins de maintenance et de collaboration.
Actuellement, DART est le seul moteur physique compatible de cette bibliothèque. Par conséquent, les tutoriels porteront sur DART. Les tutoriels initiaux suivants seront pris en compte:
- Introduction: décrit l'architecture générale de la bibliothèque Ignition Physics, les moteurs physiques compatibles et les objectifs associés.
- Installation: guide l'utilisateur pour qu'il installe éventuellement les moteurs de physique nécessaires en fonction des contextes d'application. Ce tutoriel présente également des exemples de configuration pour chaque plug-in de moteur physique permettant d'adapter une simulation spécifique.
- Utilisation du plug-in DART: décrit un exemple d'utilisation du moteur physique DART dans la simulation Gazebo. Le tutoriel consiste en une séquence d'exécutions et de configurations pour démarrer cette bibliothèque en tant que backend de la simulation Gazebo dans un exemple d'environnement spécifique.
- Créer un plug-in personnalisé: guide le nouvel utilisateur ou développeur pour créer un plug-in personnalisé basé sur un moteur physique personnalisé via certains types de fichiers de configuration (éventuellement des modèles de classe), et développe une interface entre l'API du moteur physique et l'API de cette bibliothèque. Vous pourrez noter certains contrôles d'intégrité à la fin du tutoriel.
- Utiliser plusieurs plug-ins dans une simulation (à discuter): explique comment utiliser simultanément plusieurs plug-ins au moment de l'exécution pour un exemple de simulation.
La planification des structures, des descriptions et des contenus des tutoriels sera abordée pendant la période de consolidation de la communauté. En effet, l'auteur de ces tutoriels doit s'assurer de leur validité avant de les fusionner avec le dépôt.
Pour la documentation de l'API, vous pouvez vous adapter au style de documentation Google C++ pour cette bibliothèque. Par exemple, toutes les classes doivent comporter une description au niveau de la classe. De plus, toutes les fonctions publiques doivent être documentées avec une description, tous leurs arguments, ainsi que les valeurs de retour et les exceptions possibles. Il est avantageux que les classes les plus importantes (par exemple, dartsim::RetrieveWorld, Feature, etc.) soient d'abord documentées en tant qu'approche descendante plus facile. Nous parlerons plus en détail du style de documentation et de l'identification importante de la classe lors de la période de cohésion au sein de la communauté.
Milestones
Cette section planifie un calendrier initial pour atteindre les objectifs mentionnés du projet. La planification temporelle est la suivante:
17 août – 13 sept. : création de liens avec la communauté:
- Organiser des réunions pour établir la portée du projet et la planification des didacticiels, ainsi que les attentes du rédacteur et des mentors.
- Comprendre l'ensemble du code source de la physique Ignition
Du 14 septembre au 31 octobre: élaboration des tutoriels mentionnés, avec des itérations entre les mentors et l'auteur lors de réunions.
1er novembre - 30 novembre: rédigez la documentation de l'API pour les classes les plus importantes et compilez-la à l'aide de Doxygen.
1er décembre - 5 décembre: rédigez le rapport du projet.
Après le GSoD 2020: je souhaite rester en contact avec Ignition Robotics pour améliorer et entretenir mes travaux.
Remarques finales
Il est essentiel de réviser le fichier README.md actuel sur la page d'accueil d'Ignition Physics, car l'installation du binaire à l'aide d'apt-get ne fonctionne pas sous Ubuntu 18.04. La section sur l'installation de la source doit également être révisée, car la mise en forme est incorrecte.