Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Rô-bốt đánh lửa
- Người viết nội dung kỹ thuật:
- An Thai Le
- Tên dự án:
- Hướng dẫn về Ignition Physics và tài liệu API
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
Động lực
Thư viện Ignition Physics cho phép sử dụng linh hoạt các công cụ vật lý chuyển sang phần phụ trợ của mô phỏng Ignition Gazebo. Nhiều công cụ vật lý bên ngoài có thể được điều chỉnh cho phù hợp với thư viện dưới dạng trình bổ trợ bao gồm các bộ tính năng khác nhau theo khả năng và bối cảnh ứng dụng của chúng, để hỗ trợ hoạt động mô phỏng vọng lâu. Tuy nhiên, giai đoạn hiện tại của thư viện không cung cấp:
- hướng dẫn toàn diện về cách tạo trình bổ trợ vật lý tuỳ chỉnh sử dụng công cụ vật lý tuỳ chỉnh để hỗ trợ mô phỏng
- Tài liệu API nhất quán
Đề xuất này nhằm giải quyết những vấn đề này để duy trì dự án hiệu quả hơn, đồng thời hướng dẫn người đóng góp và người dùng mới theo nguyên tắc hơn. Thông tin chi tiết về quy trình lập tài liệu sẽ được thảo luận trong phần tiếp theo, sau đó là phần mốc quan trọng để lập kế hoạch khung thời gian hoàn thành dự án. Cuối cùng, một số lưu ý về tài liệu hiện tại được đề cập.
Nội dung mô tả
Dự án này có hai mục tiêu chính:
- Tạo hướng dẫn chi tiết về cách tạo trình bổ trợ vật lý tuỳ chỉnh giao tiếp với API thư viện hiện tại.
- Cải thiện tài liệu API thư viện hiện tại cho mục đích bảo trì và cộng tác.
Hiện tại, DART là công cụ vật lý hỗ trợ duy nhất của thư viện này. Do đó, hướng dẫn sẽ xoay quanh DART. Chúng tôi sẽ xem xét các hướng dẫn ban đầu sau:
- Giới thiệu: mô tả kiến trúc cấp cao của thư viện Ignition Physics, các công cụ vật lý được hỗ trợ và mục tiêu.
- Cài đặt: hướng dẫn người dùng cài đặt các công cụ vật lý cần thiết (không bắt buộc), tuỳ thuộc vào bối cảnh của ứng dụng. Hướng dẫn này cũng minh hoạ các cấu hình mẫu cho mỗi trình bổ trợ công cụ vật lý để điều chỉnh một phiên mô phỏng cụ thể.
- Cách sử dụng trình bổ trợ DART: mô tả ví dụ về cách sử dụng công cụ vật lý DART trên mô phỏng Gazebo. Hướng dẫn này bao gồm một chuỗi các lần thực thi và cấu hình để bắt đầu thư viện này làm phần phụ trợ cho hoạt động mô phỏng Gazebo trên một môi trường ví dụ cụ thể.
- Tạo trình bổ trợ tuỳ chỉnh: hướng dẫn người dùng hoặc nhà phát triển mới tạo trình bổ trợ tuỳ chỉnh dựa trên công cụ vật lý tuỳ chỉnh thông qua một số dạng tệp cấu hình (có thể là mẫu lớp) và phát triển giao diện giữa API công cụ vật lý và API thư viện này. Bạn có thể lưu ý một số bước kiểm tra tính hợp lý ở cuối hướng dẫn này.
- Sử dụng nhiều trình bổ trợ trên một mô phỏng (cần thảo luận): mô tả cách sử dụng đồng thời nhiều trình bổ trợ trong thời gian chạy cho một mô phỏng mẫu.
Chúng ta sẽ thảo luận thêm về cấu trúc, nội dung mô tả và nội dung của hướng dẫn trong giai đoạn gắn kết cộng đồng. Tác giả của các hướng dẫn này phải đảm bảo tính hợp lệ của các bước trong hướng dẫn trước khi hợp nhất vào kho lưu trữ.
Đối với tài liệu API, bạn có thể điều chỉnh theo kiểu tài liệu Google C++ cho thư viện này. Ví dụ: tất cả các lớp đều phải có nội dung mô tả cấp lớp. Ngoài ra, tất cả hàm công khai phải được ghi lại bằng nội dung mô tả, tất cả đối số, cũng như các giá trị trả về và ngoại lệ có thể có. Bạn nên ghi lại các lớp quan trọng nhất (ví dụ: dartsim::RetrieveWorld, Feature, v.v.) trước tiên theo phương pháp từ trên xuống dễ dàng hơn. Phong cách tài liệu bổ sung, cách xác định lớp quan trọng sẽ được thảo luận trong giai đoạn gắn kết cộng đồng.
Mốc quan trọng
Phần này lập kế hoạch khung thời gian ban đầu để hoàn thành các mục tiêu đã đề cập của dự án. Lịch trình như sau:
17/8 – 13/9: Gắn kết cộng đồng:
- Thiết lập các cuộc họp để xác định phạm vi dự án và kế hoạch hướng dẫn cũng như kỳ vọng của cả người viết và người cố vấn.
- Nắm bắt bức tranh lớn về mã nguồn Vật lý đánh lửa.
14/9 — 31/10: Soạn thảo các hướng dẫn đã đề cập, đồng thời tái điều chỉnh liên tục giữa cố vấn và người viết thông qua các cuộc họp.
Ngày 1 tháng 11 – ngày 30 tháng 11: Viết tài liệu API cho các lớp quan trọng nhất và biên dịch tài liệu bằng Doxygen.
Từ ngày 1 tháng 12 đến ngày 5 tháng 12: Viết báo cáo dự án.
Sau GSoD 2020: Tôi muốn giữ liên lạc với Ignition Robotics để cải thiện và duy trì các tác phẩm của mình hơn nữa.
Ghi chú cuối cùng
Cần phải sửa đổi README.md hiện tại trên trang chủ của Ignition Physics, vì cài đặt nhị phân bằng apt-get không hoạt động trên Ubuntu 18.04. Phần cài đặt nguồn cũng cần sửa đổi do định dạng không chính xác.