Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- Ignition Robotics
- Penulis teknis:
- An Thai Le
- Nama project:
- Tutorial dan dokumentasi API Ignition Physics
- Durasi project:
- Durasi standar (3 bulan)
Project description
Motivasi
Library Ignition Physics memungkinkan penggunaan mesin fisika yang fleksibel untuk di-porting ke backend simulasi Ignition Gazebo. Banyak mesin fisika eksternal yang dapat disesuaikan dengan library sebagai plugin yang terdiri dari berbagai kumpulan fitur sesuai dengan kemampuan dan konteks aplikasinya, untuk mendukung simulasi gazebo. Namun, tahap library saat ini tidak menyediakan:
- tutorial komprehensif tentang cara membuat plugin fisika kustom yang menggunakan mesin fisika kustom untuk mendukung simulasi
- Dokumentasi API yang koheren
Proposal ini bertujuan untuk mengatasi masalah ini agar pemeliharaan project menjadi lebih baik dan memandu kontributor dan pengguna baru dengan cara yang lebih mendasar. Detail proses dokumentasi akan dibahas di bagian berikutnya, lalu diikuti dengan bagian tonggak pencapaian untuk merencanakan jangka waktu guna menyelesaikan project. Terakhir, beberapa catatan tentang dokumentasi saat ini akan disebutkan.
Deskripsi
Project ini memiliki dua sasaran utama:
- Buat tutorial mendetail tentang cara membuat plugin fisika kustom yang berinteraksi dengan API library saat ini.
- Meningkatkan dokumentasi API library saat ini untuk tujuan pemeliharaan dan kolaborasi.
Saat ini, DART adalah satu-satunya mesin fisika pendukung library ini. Oleh karena itu, tutorialnya akan berkisar pada DART. Tutorial awal ini akan dipertimbangkan:
- Pengantar: menjelaskan arsitektur tingkat tinggi library Ignition Physics, mesin fisika yang didukung, dan sasaran.
- Penginstalan: memandu pengguna untuk menginstal mesin fisika yang diperlukan secara opsional, bergantung pada konteks aplikasi. Tutorial ini juga menunjukkan contoh konfigurasi untuk setiap plugin mesin fisika guna menyesuaikan simulasi tertentu.
- Penggunaan plugin Dart: menjelaskan contoh penggunaan mesin fisika DART pada simulasi Gazebo. Tutorial ini terdiri dari urutan eksekusi dan konfigurasi untuk memulai library ini sebagai back-end untuk simulasi Gazebo di lingkungan contoh tertentu.
- Membuat plugin kustom: memandu pengguna atau developer baru untuk membuat plugin kustom berdasarkan mesin fisika kustom melalui beberapa bentuk file konfigurasi (mungkin template class), dan mengembangkan antarmuka antara API mesin fisika dan API library ini. Beberapa pemeriksaan keandalan dapat dicatat di akhir tutorial.
- Menggunakan beberapa plugin pada simulasi (perlu diskusi): menjelaskan cara menggunakan beberapa plugin secara bersamaan saat runtime untuk contoh simulasi.
Perencanaan lebih lanjut tentang struktur, deskripsi, dan konten tutorial akan dibahas dalam periode ikatan komunitas. Memang benar bahwa penulis tutorial ini harus memastikan validitas langkah-langkah tutorial sebelum menggabungkannya ke repo.
Untuk dokumentasi API, Anda dapat beradaptasi dengan gaya dokumentasi Google C++ untuk library ini. Misalnya, semua class harus memiliki deskripsi tingkat class. Selain itu, semua fungsi publik harus didokumentasikan dengan deskripsi, semua argumennya, serta kemungkinan nilai dan pengecualian yang ditampilkan. Sebaiknya class yang paling penting (misalnya dartsim::RetrieveWorld, Feature, dll.) akan didokumentasikan terlebih dahulu sebagai pendekatan top-down yang lebih mudah. Gaya dokumentasi lebih lanjut, identifikasi class penting akan dibahas dalam periode ikatan komunitas.
Pencapaian
Bagian ini merencanakan jangka waktu awal untuk menyelesaikan sasaran project yang disebutkan. Perencanaan waktu adalah sebagai berikut:
17 Agu—13 Sep: Pengikatan komunitas:
- Siapkan rapat untuk menetapkan cakupan project dan perencanaan tutorial serta ekspektasi dari penulis dan mentor.
- Pahami gambaran besar kode sumber Ignition Physics.
14 September – 31 Oktober: Membuat draf tutorial yang disebutkan dengan peningkatan iteratif antara mentor dan penulis melalui rapat.
1 Nov – 30 Nov: Menulis dokumentasi API untuk class yang paling penting dan mengompilasi dokumentasi menggunakan Doxygen.
1 Des – 5 Des: Menulis laporan project.
Setelah GSoD 2020: Saya ingin tetap terhubung dengan Ignition Robotics untuk lebih meningkatkan dan menjaga kualitas pekerjaan saya.
Catatan akhir
Anda harus merevisi README.md saat ini di halaman depan Ignition Physics, karena penginstalan biner menggunakan apt-get tidak berfungsi di Ubuntu 18.04. Bagian penginstalan sumber juga memerlukan revisi karena pemformatan yang salah.