From d4f1c20fd1a7e3c2f847b40c0a7c97ca65dfc530 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=A0togl?= Date: Sun, 16 Jan 2022 22:09:18 +0100 Subject: [PATCH 1/3] A new structure of the control.ros.org --- .../2022-01-control.ros.org-doc-restructure | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 design_drafts/2022-01-control.ros.org-doc-restructure diff --git a/design_drafts/2022-01-control.ros.org-doc-restructure b/design_drafts/2022-01-control.ros.org-doc-restructure new file mode 100644 index 0000000..3df822f --- /dev/null +++ b/design_drafts/2022-01-control.ros.org-doc-restructure @@ -0,0 +1,69 @@ +# Restructuring the documentation on control.ros.org + +The goal of this document is to provide a place for discussion of documentation restructuring on control.ros.org. +The document should result with a list of actions that have to be done to make the documentation better. + +## Motivation + +Current state of documentation is very messy, there is no clear structure and it is hard to find anything there. + + +## Goals/Targets to achieve with documentation + +### 1. We need better starting page +This page should explain in shortly what is ros2_control and what is its purpose. +A graphical representaiton of three main parts of the framework: *hardware interfaces/abstraction*, *managers (resouce and controller)*, and *controllers*. +For sure a graphics would be very, very useful there. + + +### 2. ros2_control concepts should be shown in a clear structure +The above-mentioned three concepts should be individually explained and shown in the left menu. +Each of the concepts should have multiple subpages showing details about (see the structure below). + + + + +### Proposal of the new structure + +This is a page-structure from the perspecitve of the left menu. + +Main page (when logo is clicked or control.ros.org navigated) - landing/starting/introduction page + +Architecture - shows the overall architecture of the framework; explaines differnet repositories + +1. Hardware Interface - explaines the hardware abstraction concepts: + - What is the purpose of Hardware Interface and concept of Componets + - Hardware Lifecycle + - How to utilize different concepts, e.g., Handling erorrs + +2. "ros2_control Managers": + - Resouce Manager: purpose, functionality and how can be configured and interactet with + - Controller Manager: purpose, functionality and how can be configured and interactet with + +3. Controllers - explaines the controllers concept: + - What is the purpose and how controllers work + - Controllers Lifecycle + - How to utilize differnet concepts, e.g., interface assignement, resetting values + - Standard controllers - details on standard controllers in the ros2_control repository + +4. How-To Guides (for definition see [MoveIt documentation](https://moveit.picknik.ai/main/doc/concepts/how_to_guide.html) + - Writing `` part of URDF for a robot + - Writing Hardware Interfaces + - Writing Controllers + - Migration Guides: + - migration tutorial for different versions + +5. Tutorials + - "Setting up ros2_control for a robot" + +6. Examples + - Integration ros2_control_demos repository + +7. Resources + +8. Contributing: + - Pull Requests (current page) + - Code (Rules for repsitories): some general implementation details + - Documentation + +9. Acknowledgements From a28f704bc6242c27df8766c64a685c47abd3db02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=A0togl?= Date: Fri, 4 Mar 2022 18:41:16 +0100 Subject: [PATCH 2/3] Update design_drafts/2022-01-control.ros.org-doc-restructure Co-authored-by: Bence Magyar --- design_drafts/2022-01-control.ros.org-doc-restructure | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/design_drafts/2022-01-control.ros.org-doc-restructure b/design_drafts/2022-01-control.ros.org-doc-restructure index 3df822f..dce890e 100644 --- a/design_drafts/2022-01-control.ros.org-doc-restructure +++ b/design_drafts/2022-01-control.ros.org-doc-restructure @@ -37,8 +37,8 @@ Architecture - shows the overall architecture of the framework; explaines differ - How to utilize different concepts, e.g., Handling erorrs 2. "ros2_control Managers": - - Resouce Manager: purpose, functionality and how can be configured and interactet with - - Controller Manager: purpose, functionality and how can be configured and interactet with + - Controller Manager: purpose, functionality and how can be configured and interacted with + - Resouce Manager: purpose, functionality and how can be configured and interacted with 3. Controllers - explaines the controllers concept: - What is the purpose and how controllers work From 7b63438f9e39fe5cec93a697d26c290514ea0c2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Denis=20=C5=A0togl?= Date: Fri, 4 Mar 2022 18:41:48 +0100 Subject: [PATCH 3/3] Update design_drafts/2022-01-control.ros.org-doc-restructure --- design_drafts/2022-01-control.ros.org-doc-restructure | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/design_drafts/2022-01-control.ros.org-doc-restructure b/design_drafts/2022-01-control.ros.org-doc-restructure index dce890e..5bdc125 100644 --- a/design_drafts/2022-01-control.ros.org-doc-restructure +++ b/design_drafts/2022-01-control.ros.org-doc-restructure @@ -38,7 +38,7 @@ Architecture - shows the overall architecture of the framework; explaines differ 2. "ros2_control Managers": - Controller Manager: purpose, functionality and how can be configured and interacted with - - Resouce Manager: purpose, functionality and how can be configured and interacted with + - Resource Manager: purpose, functionality and how can be configured and interacted with 3. Controllers - explaines the controllers concept: - What is the purpose and how controllers work