Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Ignition Robotics
- Redactor técnico:
- An Thai Le
- Nombre del proyecto:
- Instructivos de Ignition Physics y documentación de la API
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Motivación
La biblioteca de Ignition Physics permite un uso flexible de los motores físicos que se portan al back-end 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 potenciar la simulación de glorieta. Sin embargo, la etapa actual de la biblioteca no proporciona lo siguiente:
- instructivos integrales sobre la creación de complementos de física personalizados que usan motores de física personalizados para potenciar 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 nuevos colaboradores y usuarios de una manera más objetiva. Los detalles del proceso de documentación se analizarán en la siguiente sección y, luego, la sección de hitos para planificar el marco de tiempo 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 sobre la creación de una interfaz de complemento de física personalizado con la API de la biblioteca actual.
- Se mejoró 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 de esta biblioteca. Por lo tanto, los tutoriales se centrarán en DART. Consideraremos estos instructivos iniciales:
- Introducción: Describe la arquitectura de alto nivel de la biblioteca de Ignition Physics, los motores físicos compatibles y los objetivos.
- Instalación: Guía al usuario para que, de manera opcional, instale los motores físicos necesarios según los contextos de la aplicación. En este instructivo, también se muestran parámetros de configuración de ejemplo para cada complemento de motor de física para adaptar una simulación específica.
- Uso del complemento de Dart: describe el uso de ejemplo del motor físico de DART en la simulación de Gazebo. El tutorial consiste en una secuencia de ejecuciones y configuraciones para iniciar esta biblioteca como back-end para 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 algunas formas de archivos de configuración (posiblemente plantillas de clase) y desarrolla una interfaz entre la API de Physical Engine y esta API de biblioteca. Algunas verificaciones de estado se pueden observar al final del instructivo.
- Cómo usar varios complementos en una simulación (se necesita análisis): Se describe cómo usar varios complementos de forma simultánea en el tiempo de ejecución para una simulación de ejemplo.
En el período de fortalecimiento de la comunidad, se analizará la planificación adicional de las estructuras, las descripciones y el contenido de los tutoriales. Es cierto que el autor de estos tutoriales debe garantizar la validez de los pasos del tutorial antes de fusionarlos con el repositorio.
En el caso de la documentación de la API, es posible adaptar esta biblioteca al estilo de documentación de C++ de Google. Por ejemplo, todas las clases deben tener una descripción a nivel de la clase. Además, todas las funciones públicas deben documentarse con una descripción, todos sus argumentos, así como posibles valores de retorno y excepciones. Es beneficioso que las clases más importantes (p. ej., dartsim::RetrieveWorld, Feature, etc.) se documenten primero como un enfoque descendente más sencillo. En el período para establecer vínculos con la comunidad, se analizarán las identificaciones importantes de las clases y el estilo de documentación adicional.
Milestones
En esta sección, se planifica un plazo inicial para completar los objetivos del proyecto mencionados. La planificación del tiempo es la siguiente:
Del 17 de agosto al 13 de septiembre: Vínculos con la comunidad:
- Organiza reuniones para establecer el alcance del proyecto y las planificaciones de tutoriales, así como las expectativas tanto del escritor como de los mentores.
- Capta el panorama completo del código fuente de Ignition Physics.
Del 14 de septiembre al 31 de octubre: Redacta los instructivos mencionados con perfeccionamiento iterativo entre los mentores y el escritor a través de reuniones.
Del 1 al 30 de noviembre: Escribe documentación sobre las APIs 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 en contacto con Ignition Robotics para seguir mejorando y mantener mis trabajos.
Notas finales
Es fundamental revisar el archivo README.md actual de la primera página de Ignition Physics, ya que la instalación del objeto binario con apt-get no funciona en Ubuntu 18.04. La sección de instalación fuente también necesita revisión debido a que el formato es incorrecto.