En esta página, se incluyen los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- Ignition Robotics
- Redactor técnico:
- An Thai Le
- Nombre del proyecto:
- Instructivos y documentación de la API de Ignition Physics
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Motivación
La biblioteca de Ignition Physics permite usar de manera flexible los motores físicos que se trasladan al backend de la simulación de Ignition Gazebo. Muchos motores físicos externos pueden adaptarse a la biblioteca como complementos que constan de diferentes conjuntos de funciones según sus capacidades y contextos de aplicación, para impulsar la simulación de la glorieta. Sin embargo, la etapa actual de la biblioteca no proporciona lo siguiente:
- instructivos detallados sobre la creación de complementos de física personalizados que usan motores de física personalizados para impulsar la simulación
- Documentación de la API coherente
El objetivo de esta propuesta es resolver estos problemas para mejorar el mantenimiento del proyecto y guiar a los colaboradores y usuarios nuevos de una manera más Principiante. Los detalles del proceso de documentación se analizarán en la siguiente sección y, luego, se seguirá con la sección de eventos importantes para planificar el período para completar el proyecto. Por último, se mencionan algunas notas sobre la documentación actual.
Descripción
Este proyecto tiene dos objetivos principales:
- Crea instructivos detallados para crear complementos de física personalizados que interactúen con la API de la biblioteca actual.
- Mejora la documentación actual de la API de la biblioteca con fines de mantenimiento y colaboración.
Actualmente, DART es el único motor de física compatible con esta biblioteca. Por lo tanto, los instructivos girarán en torno a DART. Estos instructivos iniciales se considerarán:
- Introducción: Describe la arquitectura de alto nivel de la biblioteca de Ignition Physics, los motores de física compatibles y los objetivos.
- Instalación: Guía al usuario para que instale de forma opcional los motores de física necesarios según los contextos de la aplicación. En este instructivo, también se muestran ejemplos de configuraciones para cada complemento del motor de física para adaptar una simulación específica.
- Uso del complemento DART: Describe el uso de ejemplo del motor de física de DART en la simulación de Gazebo. El instructivo consta de una secuencia de ejecuciones y configuraciones para iniciar esta biblioteca como el backend de la simulación de Gazebo en un entorno de ejemplo específico.
- Crear complemento personalizado: Guía al usuario o desarrollador nuevo para que cree un complemento personalizado basado en un motor de física personalizado a través de algunos tipos de archivos de configuración (posiblemente plantillas de clase) y desarrolla una interfaz entre la API del motor de física y esta API de biblioteca. Algunas verificaciones de coherencia se pueden observar al final del instructivo.
- Uso de varios complementos en una simulación (se necesita debate): Describe cómo usar varios complementos de forma simultánea durante el tiempo de ejecución para una simulación de ejemplo.
Durante el período de vinculación con la comunidad, se analizará la planificación adicional de las estructuras, las descripciones y el contenido de los instructivos. Es cierto que el autor de estos instructivos debe garantizar la validez de los pasos antes de combinarlos en el repositorio.
En el caso de la documentación de la API, es posible adaptarse al estilo de documentación de Google C++ para esta biblioteca. Por ejemplo, todas las clases deben tener una descripción a nivel de la clase. Además, todas las funciones públicas deben estar documentadas con una descripción, todos sus argumentos, así como los posibles valores y excepciones que devuelven. Es conveniente que las clases más importantes (p. ej., dartsim::RetrieveWorld, Feature, etc.) se documenten primero como un enfoque descendente más sencillo. Se analizará más a fondo el estilo de la documentación y la identificación importante de las clases durante el período de vinculación con la comunidad.
Milestones
En esta sección, se planifica un plazo inicial para completar los objetivos mencionados del proyecto. La planificación del tiempo es la siguiente:
Del 17 de agosto al 13 de septiembre: Fortalecimiento de la comunidad:
- Programa reuniones para establecer los alcances del proyecto y la planificación de los instructivos, así como las expectativas del escritor y los mentores.
- Comprender el panorama general del código fuente de Ignition Physics
Del 14 de septiembre al 31 de octubre: Redacta los instructivos mencionados con iteraciones de perfeccionamiento entre los mentores y el escritor a través de reuniones.
Del 1 al 30 de noviembre: Escribe la documentación de la API para las clases más importantes y compila la documentación con Doxygen.
Del 1 al 5 de diciembre: Escribe el informe del proyecto.
Después de GSoD 2020: Me gustaría mantenerme conectado con Ignition Robotics para mejorar y mantener mis trabajos.
Notas finales
Es fundamental revisar el archivo README.md actual en la página principal de Ignition Physics, ya que la instalación binaria con apt-get no funciona en Ubuntu 18.04. La sección de instalación de la fuente también debe revisarse debido al formato incorrecto.