Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- Ignition Robotics
- Redator técnico:
- An Thai Le
- Nome do projeto:
- Tutoriais e documentação da API do Ignition Physics
- Duração do projeto:
- Duração padrão (três meses)
Project description
Motivação
A biblioteca Ignition Physics permite o uso flexível da portabilidade de mecanismos de física para o back-end da simulação do Ignition Gazebo. Muitos mecanismos de física externos podem ser adaptados à biblioteca como plug-ins que consistem em diferentes conjuntos de recursos de acordo com suas capacidades e contextos de aplicativo, a fim de potencializar a simulação de gazebo. No entanto, a fase atual da biblioteca não oferece:
- Tutoriais abrangentes sobre como criar plug-ins de física personalizados que usam mecanismos de física personalizados para impulsionar a simulação
- Documentação da API coerente
O objetivo desta proposta é resolver esses problemas para melhorar a manutenção do projeto e orientar novos colaboradores e usuários de maneira mais simples. Os detalhes do processo de documentação serão discutidos na próxima seção e seguidos pela seção de marcos para planejar o período de conclusão do projeto. Por fim, são mencionadas algumas observações sobre a documentação atual.
Descrição
O projeto tem dois objetivos principais:
- Criar tutoriais detalhados sobre como criar uma interface de plug-in de física personalizada com a API da biblioteca atual.
- Aprimorar a documentação atual da API da biblioteca para fins de manutenção e colaboração.
Atualmente, o DART é o único mecanismo de física de suporte dessa biblioteca. Portanto, os tutoriais giram em torno do Dart. Estes tutoriais iniciais serão considerados:
- Introdução: descreve a arquitetura de alto nível da biblioteca Ignition Physics, os mecanismos de física compatíveis e as metas.
- Instalação: orienta o usuário a instalar os motores de física necessários, opcionalmente, dependendo dos contextos do aplicativo. Este tutorial também mostra exemplos de configurações para cada plug-in do motor de física para adaptar uma simulação específica.
- Uso do plug-in do DART: descreve o uso do mecanismo de física do DART na simulação do Gazebo. O tutorial consiste em uma sequência de execuções e configurações para iniciar essa biblioteca como o back-end da simulação do Gazebo em um ambiente de exemplo específico.
- Criar plug-in personalizado: orienta o novo usuário ou desenvolvedor a criar um plug-in personalizado com base no mecanismo de física personalizado usando algumas formas de arquivos de configuração (possivelmente modelos de classe) e desenvolve uma interface entre a API do mecanismo de física e a API da biblioteca. Algumas verificações de integridade podem ser observadas no final do tutorial.
- Como usar vários plug-ins em uma simulação (precisa de discussão): descreve como usar vários plug-ins simultaneamente no momento da execução para um exemplo de simulação.
O planejamento adicional sobre estruturas, descrições e conteúdos de tutoriais será discutido no período de integração da comunidade. O autor desses tutoriais precisa garantir a validade das etapas do tutorial antes de mesclar no repositório.
Para a documentação da API, é possível adaptar o estilo de documentação do Google C++ para essa biblioteca. Por exemplo, todas as classes precisam ter uma descrição no nível da classe. Além disso, todas as funções públicas precisam ser documentadas com uma descrição, todos os argumentos e possíveis valores de retorno e exceções. É benéfico que as classes mais importantes (por exemplo, dartsim::RetrieveWorld, Feature etc.) sejam documentadas primeiro como uma abordagem descendente mais fácil. Outro estilo de documentação e importantes identificações de classe serão discutidas no período de vínculo com a comunidade.
Milestones
Esta seção planeja um período inicial para concluir as metas mencionadas do projeto. O planejamento do tempo é o seguinte:
17 de agosto a 13 de setembro: fortalecimento da comunidade:
- Marque reuniões para estabelecer os escopos do projeto e os planos dos tutoriais, bem como as expectativas do redator e dos mentores.
- Entenda o código-fonte do Ignition Physics.
De 14 de setembro a 31 de outubro: elabore os tutoriais mencionados com refinamentos iterativos entre mentores e o redator por meio de reuniões.
1 a 30 de novembro: escrever a documentação da API para as classes mais importantes e compilar a documentação usando o Doxygen.
De 1o a 5 de dezembro: escreva o relatório do projeto.
Após o GSoD 2020: quero continuar conectado com a Ignition Robotics para melhorar e manter ainda mais meu trabalho.
Observações finais
É essencial revisar o README.md atual na página inicial de Ignition Physics, porque a instalação binária usando apt-get não funciona no Ubuntu 18.04. A seção de instalação de origem também precisa de revisão devido à formatação incorreta.