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:
- Ignition Robotics
- Rédacteur technique:
- Le Thaï
- Nom du projet:
- Tutoriels Ignition Physics et documentation sur l'API
- Durée du projet:
- Durée standard (3 mois)
Project description
Motivation
La bibliothèque Ignition Physics permet d'utiliser de façon flexible le portage des moteurs physiques dans le backend de la simulation Ignition Gazebo. De nombreux moteurs physiques 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 leur contexte d'application, afin d'alimenter la simulation de kiosque. Toutefois, l'étape actuelle de la bibliothèque ne fournit pas:
- des tutoriels complets sur la création de plug-ins de physique personnalisés qui utilisent des moteurs physiques personnalisés pour faire des simulations
- documentation de l'API cohérente
Cette proposition vise à résoudre ces problèmes pour améliorer la maintenance du projet et à guider les nouveaux contributeurs et utilisateurs selon un principe plus fondamental. 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 la documentation actuelle sont mentionnées.
Description
Ce projet a deux objectifs principaux:
- Créer des tutoriels détaillés sur la création de plug-ins de physique personnalisés qui interagissent avec l'API de la bibliothèque actuelle
- Amélioration de la documentation actuelle des API de la bibliothèque à des fins de maintenance et de collaboration.
Actuellement, DART est le seul moteur physique compatible avec cette bibliothèque. Par conséquent, les didacticiels seront axés sur DART. Ces premiers tutoriels seront abordés:
- Introduction: décrit l'architecture de haut niveau de la bibliothèque Ignition Physics, les moteurs physiques compatibles et les objectifs.
- Installation: guide l'utilisateur pour qu'il puisse installer les moteurs physiques nécessaires en fonction du contexte de l'application. Ce tutoriel présente également des exemples de configurations 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 de DART dans la simulation de kiosques. Le tutoriel consiste en une séquence d'exécutions et de configurations permettant de démarrer cette bibliothèque en tant que backend pour la simulation de kiosques sur un exemple d'environnement spécifique.
- Créer un plug-in personnalisé: guide un nouvel utilisateur ou un développeur pour qu'il crée un plug-in personnalisé basé sur un moteur physique personnalisé à l'aide de certains types de fichiers de configuration (éventuellement des modèles de classe), et développe une interface entre l'API Physical Engine et cette API de bibliothèque. Vous pourrez effectuer certains contrôles d'intégrité à la fin du tutoriel.
- Utiliser plusieurs plug-ins dans une simulation (discussion requise): décrit comment utiliser simultanément plusieurs plug-ins au moment de l'exécution pour un exemple de simulation.
Nous discuterons plus en détail de la structure, de la description et du contenu des tutoriels pendant la période d'association avec la communauté. L'auteur de ces tutoriels doit s'assurer de la validité des étapes du tutoriel avant de procéder à la fusion dans le dépôt.
Pour la documentation de l'API, il est possible de s'adapter au style de documentation Google C++ de cette bibliothèque. Par exemple, toutes les classes doivent comporter une description au niveau du cours. De plus, toutes les fonctions publiques doivent être documentées avec une description, tous leurs arguments, ainsi que les éventuelles valeurs renvoyées et les exceptions. Il est préférable que les classes les plus importantes (par exemple dartsim::RetrieveWorld, etc.) soient d'abord documentées afin de faciliter l'approche descendante. Davantage de documentation et l'identification importante de la classe seront abordées pendant la période de cohésion de la communauté.
Milestones
Cette section planifie un délai initial pour atteindre les objectifs mentionnés du projet. La planification du temps est la suivante:
17 août – 13 sept. : Engagement avec une communauté:
- Organiser des réunions pour établir la portée des projets et la planification des tutoriels, ainsi que les attentes du rédacteur et des mentors.
- Familiarisez-vous avec le code source d'IgnitionPhysics dans son ensemble.
14 sept. – 31 octobre: élaborez les tutoriels mentionnés avec des améliorations itératives entre mentors et rédacteurs lors de réunions.
1er nov. – 30 nov. : rédaction de la documentation sur les API pour les classes les plus importantes et compilation à l'aide de Doxygen.
1er déc. – 5 déc. : Rédaction du rapport du projet.
Après la conférence GSoD 2020: je souhaiterais rester en contact avec Ignition Robotics pour continuer à améliorer et à gérer mes travaux.
Notes finales
Il est essentiel de réviser le fichier README.md actuel figurant sur la première page d'Ignition Physics, car l'installation binaire à l'aide d'apt-get ne fonctionne pas sur Ubuntu 18.04. La section d'installation du code source doit également être révisée en raison d'une mise en forme incorrecte.