feat: change the adapi page structure (#406)

* move user stories

Signed-off-by: Takagi, Isamu <[email protected]>

* move features

Signed-off-by: Takagi, Isamu <[email protected]>

* add list page

Signed-off-by: Takagi, Isamu <[email protected]>

* update message

Signed-off-by: Takagi, Isamu <[email protected]>

* update menu

Signed-off-by: Takagi, Isamu <[email protected]>

---------

Signed-off-by: Takagi, Isamu <[email protected]>

docs/design/autoware-interfaces/ad-api/.pages

@@ -1,4 +1,5 @@
 nav:
   - index.md
-  - use-cases
+  - features
   - list
+  - types

docs/design/autoware-interfaces/ad-api/list/api/fail_safe/index.md → docs/design/autoware-interfaces/ad-api/features/fail-safe.md

@@ -1,4 +1,6 @@
-# Fail-safe API
+# Fail-safe
+
+## Related API
 
 - {{ link_ad_api('/api/fail_safe/mrm_state') }}
 
@@ -11,14 +13,14 @@ For safety, Autoware switches the operation to MRM when an abnormality is detect
 Since the required behavior differs depending on the situation, MRM is implemented in various places as a specific mode in a normal module or as an independent module.
 The fail-safe module selects the behavior of MRM according to the abnormality and switches the gate output to that command.
 
-![fail-safe-architecture](./architecture.drawio.svg)
+![fail-safe-architecture](./fail-safe/architecture.drawio.svg)
 
 ## States
 
 The MRM state indicates whether MRM is operating. This state also provides success or failure.
 Generally, MRM will switch to another behavior if it fails.
 
-![mrm-state](./mrm-state.drawio.svg)
+![mrm-state](./fail-safe/mrm-state.drawio.svg)
 
 | State     | Description                                                |
 | --------- | ---------------------------------------------------------- |
@@ -32,7 +34,7 @@ Generally, MRM will switch to another behavior if it fails.
 There is a dependency between MRM behaviors. For example, it switches from a comfortable stop to a emergency stop, but not the other way around.
 This is service dependent. Autoware supports the following transitions by default.
 
-![mrm-behavior](./mrm-behavior.drawio.svg)
+![mrm-behavior](./fail-safe/mrm-behavior.drawio.svg)
 
 | State            | Description                                                               |
 | ---------------- | ------------------------------------------------------------------------- |

docs/design/autoware-interfaces/ad-api/list/api/interface/index.md → docs/design/autoware-interfaces/ad-api/features/interface.md

@@ -1,4 +1,6 @@
-# Interface API
+# Interface
+
+## Related API
 
 - {{ link_ad_api('/api/interface/version') }}
 

docs/design/autoware-interfaces/ad-api/list/api/localization/index.md → docs/design/autoware-interfaces/ad-api/features/localization.md

@@ -1,4 +1,6 @@
-# Localization API
+# Localization
+
+## Related API
 
 - {{ link_ad_api('/api/localization/initialization_state') }}
 - {{ link_ad_api('/api/localization/initialize') }}
@@ -9,7 +11,7 @@ This API manages the initialization of localization. Autoware requires a global
 
 ## States
 
-![localization-initialization_state-state](./state.drawio.svg)
+![localization-initialization-state](./localization/state.drawio.svg)
 
 | State         | Description                                                                      |
 | ------------- | -------------------------------------------------------------------------------- |

docs/design/autoware-interfaces/ad-api/list/api/motion/index.md → docs/design/autoware-interfaces/ad-api/features/motion.md

@@ -1,4 +1,6 @@
-# Motion API
+# Motion
+
+## Related API
 
 - {{ link_ad_api('/api/motion/state') }}
 - {{ link_ad_api('/api/motion/accept_start') }}
@@ -17,7 +19,7 @@ In this state, calling the start API changes the state to MOVING and the vehicle
 This mechanism can add processing such as announcements before the vehicle starts.
 Depending on the configuration, the state may transition directly from STOPPED to MOVING.
 
-![motion-state](./docs/state.drawio.svg)
+![motion-state](./motion/state.drawio.svg)
 
 | State            | Description                                     |
 | ---------------- | ----------------------------------------------- |

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/index.md → docs/design/autoware-interfaces/ad-api/features/operation_mode.md

@@ -1,4 +1,6 @@
-# Operation Mode API
+# Operation mode
+
+## Related API
 
 - {{ link_ad_api('/api/operation_mode/state') }}
 - {{ link_ad_api('/api/operation_mode/change_to_autonomous') }}
@@ -22,7 +24,7 @@ Autoware control mode has four operation modes.
 | Local      | Manually control the vehicle from nearby with some device such as a joystick. |
 | Remote     | Manually control the vehicle from a web application on the cloud.             |
 
-![operation-mode-architecture](./architecture.drawio.svg)
+![operation-mode-architecture](./operation_mode/architecture.drawio.svg)
 
 ## States
 

docs/design/autoware-interfaces/ad-api/features/planning-factors.md

@@ -1,5 +1,70 @@
 # Planning factors
 
-!!! warning
+## Related API
 
-    Under Construction
+- {{ link_ad_api('/api/planning/velocity_factors') }}
+- {{ link_ad_api('/api/planning/steering_factors') }}
+
+## Description
+
+This API manages the planned behavior of the vehicle.
+Applications can notify the vehicle behavior to the people around and visualize it for operator and passengers.
+
+## Velocity factors
+
+The velocity factors is an array of information on the behavior that the vehicle stops (or slows down).
+Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type.
+As the vehicle approaches the stop position, this factor appears with a status of APPROACHING.
+And when the vehicle reaches that position and stops, the status will be STOPPED.
+The pose indicates the stop position or the base link if the stop position cannot be calculated.
+
+![velocity-factors](./planning-factors/velocity-factors.drawio.svg)
+
+| Factor Type                 | Description                                                              |
+| --------------------------- | ------------------------------------------------------------------------ |
+| SURROUNDING_OBSTACLE        | There are obstacles immediately around the vehicle.                      |
+| ROUTE_OBSTACLE              | There are obstacles along the route ahead.                               |
+| INTERSECTION                | There are obstacles in other lanes in the path.                          |
+| CROSSWALK                   | There are obstacles on the crosswalk.                                    |
+| REAR_CHECK                  | There are obstacles behind that would be in a human driver's blind spot. |
+| USER_DEFINED_DETECTION_AREA | There are obstacles in the predefined detection area.                    |
+| NO_STOPPING_AREA            | There is not enough space beyond the no stopping area.                   |
+| STOP_SIGN                   | A stop by a stop sign.                                                   |
+| TRAFFIC_SIGNAL              | A stop by a traffic signal.                                              |
+| V2I_GATE_CONTROL_ENTER      | A stop by a V2I gate entering.                                           |
+| V2I_GATE_CONTROL_LEAVE      | A stop by a V2I gate leaving.                                            |
+| MERGE                       | A stop before merging lanes.                                             |
+| SIDEWALK                    | A stop before crossing the sidewalk.                                     |
+| LANE_CHANGE                 | A lane change.                                                           |
+| AVOIDANCE                   | A path change to avoid an obstacle in the current lane.                  |
+| EMERGENCY_OPERATION         | A stop by emergency instruction from the operator.                       |
+
+## Steering factors
+
+The steering factors is an array of information on the maneuver that requires use of turn indicators, such as turning left or right.
+Each factor has a type shown below, pose in the base link, distance, status, and detailed data depending on its type.
+As the vehicle approaches the position to start steering, this factor appears with a status of APPROACHING.
+And when the vehicle reaches that position, the status will be TURNING.
+The pose indicates the start position when APPROACHING and the end position when TURNING.
+
+![steering-factors-1](./planning-factors/steering-factors-1.drawio.svg)
+
+In cases such as lane change and avoidance, the vehicle will start steering at any position in the range depending on the situation.
+As the vehicle approaches the start position of the range, this factor appears with a status of APPROACHING.
+And when the vehicle reaches that position, the status will be TRYING.
+Then, when it is possible, the vehicle will start steering and the status will be TURNING.
+The pose indicates the start of the range (A) when APPROACHING and the end of the range (B) when TRYING.
+The position to end steering (C to D) for TURNING depends on the position to start steering.
+
+![steering-factors-2](./planning-factors/steering-factors-2.drawio.svg)
+
+| Factor Type           | Description                                                              |
+| --------------------- | ------------------------------------------------------------------------ |
+| INTERSECTION          | A turning left or right at an intersection.                              |
+| LANE_CHANGE           | A lane change.                                                           |
+| AVOIDANCE_PATH_CHANGE | A path change to avoid an obstacle in the current lane.                  |
+| AVOIDANCE_PATH_RETURN | A path change to return to the original lane after avoiding an obstacle. |
+| STATION               | T.B.D. (bus stop)                                                        |
+| PULL_OUT              | T.B.D.                                                                   |
+| PULL_OVER             | T.B.D.                                                                   |
+| EMERGENCY_OPERATION   | A path change by emergency instruction from the operator.                |

docs/design/autoware-interfaces/ad-api/list/api/routing/index.md → docs/design/autoware-interfaces/ad-api/features/routing.md

@@ -1,4 +1,6 @@
-# Route API
+# Routing
+
+## Related API
 
 - {{ link_ad_api('/api/routing/state') }}
 - {{ link_ad_api('/api/routing/route') }}
@@ -14,7 +16,7 @@ There are two ways to set the route. The one is a generic method that uses pose,
 
 ## States
 
-![route-state](./state.drawio.svg)
+![route-state](./routing/state.drawio.svg)
 
 | State    | Description                                        |
 | -------- | -------------------------------------------------- |

docs/design/autoware-interfaces/ad-api/index.md

@@ -1,7 +1,39 @@
-# AD API
+# Autoware AD API
 
-!!! warning
+## Overview
 
-    Under Construction
+Autoware AD API is the interface for operating the vehicle from outside the autonomous driving system.
+[See here for the overall interface design of Autoware.](../index.md)
 
-See [here](../index.md) for an overview.
+## User stories
+
+The user stories are service scenarios that AD API assumes. AD API is designed based on these scenarios.
+Each scenario is realized by a combination of use cases described later.
+If there are scenarios that cannot be covered, please discuss adding a user story.
+
+- [Bus service](./stories/bus-service.md)
+- [Taxi service](./stories/taxi-service.md)
+
+## Use cases
+
+Use cases are partial scenarios derived from the user story and generically designed.
+Service providers can combine these use cases to define user stories and check if AD API can be applied to their own scenarios.
+
+- [Launch and terminate](./use-cases/launch-terminate.md)
+- [Initialize the pose](./use-cases/initialize-pose.md)
+- [Change the operation mode](./use-cases/change-operation-mode.md)
+- [Drive to the designated position](./use-cases/drive-designated-position.md)
+- [Get on and get off](./use-cases/get-on-off.md)
+- [Vehicle monitoring](./use-cases/vehicle-monitoring.md)
+- [Request to cooperate](./use-cases/request-to-cooperate.md)
+
+## Features
+
+- [Interface](./features/interface.md)
+- [Operation Mode](./features/operation_mode.md)
+- [Routing](./features/routing.md)
+- [Localization](./features/localization.md)
+- [Motion](./features/motion.md)
+- [Planning](./features/planning-factors.md)
+- [Fail-safe](./features/fail-safe.md)
+- [Vehicle status](./features/vehicle-status.md)

docs/design/autoware-interfaces/ad-api/list/api/fail_safe/mrm_state.md

@@ -12,5 +12,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Get the MRM state. For details, see the [fail-safe](./index.md).
+Get the MRM state.
+For details, see the [fail-safe](../../../features/fail-safe.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/localization/initialization_state.md

@@ -5,10 +5,11 @@ type:
   name: autoware_adapi_v1_msgs/msg/LocalizationInitializationState
   msg:
     - name: state
-      text: A value of the [localization initialization state](./index.md).
+      text: A value of the localization initialization state.
 ---
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Get the initialization state of localization. For details, see the [localization initialization state](./index.md).
+Get the initialization state of localization.
+For details, see the [localization](../../../features/localization.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/localization/initialize.md

@@ -13,5 +13,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Request to initialize localization. For details, see the [pose state](./index.md).
+Request to initialize localization.
+For details, see the [localization](../../../features/localization.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/motion/accept_start.md

@@ -10,5 +10,5 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Accept the vehicle to start. This API can be used when the [motion state](./index.md) is STARTING.
+Accept the vehicle to start. This API can be used when the [motion state](../../../features/motion.md) is STARTING.
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/motion/state.md

@@ -10,5 +10,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Get the motion state. For details, see the [motion state](./index.md).
+Get the motion state.
+For details, see the [motion state](../../../features/motion.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_autonomous.md

@@ -10,5 +10,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Change the operation mode to autonomous. For details, see the [operation mode](./index.md).
+Change the operation mode to autonomous.
+For details, see the [operation mode](../../../features/operation_mode.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_local.md

@@ -10,5 +10,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Change the operation mode to local. For details, see the [operation mode](./index.md).
+Change the operation mode to local.
+For details, see the [operation mode](../../../features/operation_mode.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_remote.md

@@ -10,5 +10,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Change the operation mode to remote. For details, see the [operation mode](./index.md).
+Change the operation mode to remote.
+For details, see the [operation mode](../../../features/operation_mode.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/change_to_stop.md

@@ -10,5 +10,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Change the operation mode to stop. For details, see the [operation mode](./index.md).
+Change the operation mode to stop.
+For details, see the [operation mode](../../../features/operation_mode.md).
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/disable_autoware_control.md

@@ -10,6 +10,7 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Disable vehicle control by Autoware. For details, see the [operation mode](./index.md).
+Disable vehicle control by Autoware.
+For details, see the [operation mode](../../../features/operation_mode.md).
 This API fails if the vehicle does not support mode change by software.
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/enable_autoware_control.md

@@ -10,6 +10,7 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Enable vehicle control by Autoware. For details, see the [operation mode](./index.md).
+Enable vehicle control by Autoware.
+For details, see the [operation mode](../../../features/operation_mode.md).
 This API fails if the vehicle does not support mode change by software.
 {% endblock %}

docs/design/autoware-interfaces/ad-api/list/api/operation_mode/state.md

@@ -22,5 +22,6 @@ type:
 
 {% extends 'design/autoware-interfaces/templates/autoware-interface.jinja2' %}
 {% block description %}
-Get the operation mode state. For details, see the [operation mode](./index.md).
+Get the operation mode state.
+For details, see the [operation mode](../../../features/operation_mode.md).
 {% endblock %}