update documents

autowarefoundation · Feb 4, 2022 · 5a7f1a9 · 5a7f1a9
1 parent cf130ae
commit 5a7f1a9
Show file tree

Hide file tree

Showing 6 changed files with 177 additions and 170 deletions.
diff --git a/docs/installation/index.md b/docs/installation/index.md
@@ -1,21 +1,20 @@
-Installation {#installation}
-============================
+# Installation
 
-The supported environments are specified in @subpage target-environments.
+The supported environments are specified in [target-environments](target-environments.md).
 
 The recommended method for installation is through the use of [ADE](https://ade-cli.readthedocs.io/en/latest/),
 a Docker-based tool to ensure that all developers in a project have a common, consistent development
 environment. It comes with a pre-built version of Autoware.Auto, so that you will not need to compile it yourself
 if you do not want to.
 
-- @subpage installation-ade
-- @subpage installation-ade-arm64
+- [installation-ade](installation-ade.md)
+- [installation-ade-arm64](installation-ade-arm64.md)
 
-Autoware.Auto can also be built without the use of [ADE](https://ade-cli.readthedocs.io/en/latest/)
+Autoware.Core can also be built without the use of [ADE](https://ade-cli.readthedocs.io/en/latest/)
 for cases where a more granular control of the installation environment is needed.
 
-- @subpage installation-no-ade
+- [installation-no-ade](installation-no-ade.md)
 
 A prerequisite for running the full software stack with simulation is the LGSVL simulator:
 
-- @subpage lgsvl
+- [lgsvl](lgsvl.md)
diff --git a/docs/installation/installation-ade-arm64.md b/docs/installation/installation-ade-arm64.md
@@ -1,70 +1,73 @@
-Installation with ADE for arm64 Systems {#installation-ade-arm64}
-=======================================
+# Installation with ADE for arm64 Systems
 
-@tableofcontents
+## Goals
 
-# Goals {#installation-and-development-goals-arm64}
-
-This article demonstrates how to launch AutowareAuto using ADE for `arm64` systems and those
-wishing to develop using `arm64`. 
+This article demonstrates how to launch Autoware.Core using ADE for `arm64` systems and those
+wishing to develop using `arm64`.
 This document will cover both native and non-native systems using ADE.
 
-# Native arm64 System {#native-arm64-installation}
+## Native arm64 System
 
 The following section describes the process required to launch the ade environment on an `arm64`
 based system.
 
-## Prerequisites
+### Prerequisites
 
 Ensure that ADE has been installed and the `.adehome` file has been created. To complete this,
-follow the instructions in @ref installation-and-development-install-ade then subsequently @ref
-installation-and-development-setup-ade-home-and-project-checkout.
+follow the instructions in [Install ADE](installation-ade.md#install-ade) then subsequently [Setup ADE home and project checkout](installation-ade.md#setup-ade-home-and-project-checkout).
 
-## Launch ADE arm64 Docker
+### Launch ADE arm64 Docker
 
 Enter the development directory and launch the ADE docker:
 
 ```{bash}
-$ cd ~/adehome/AutowareAuto
-$ ade --rc .aderc-arm64 start --update --enter
+cd ~/adehome/AutowareCore
+ade --rc .aderc-arm64 start --update --enter
 ```
 
-# Non-native arm64 System {#non-native-arm64-installation}
+## Non-native arm64 System
 
 The following section describes the process to run multi-architecture systems using Docker,
 `binfmt`, and `qemu`.
 
-## Prerequisites
+### Prerequisites
 
 Before alternative architectures can be run on a system, ensure that one can run ADE and
-AutowareAuto on the native architecture.
-Those with `amd64` systems should follow the instructions in @ref installation-ade and ensure
+Autoware.Core on the native architecture.
+Those with `amd64` systems should follow the instructions in [Installation with ADE](installation-ade.md) and ensure
 all dependencies are properly installed.
-The following will assume that all ADE and AutowareAuto dependencies have been installed.
+The following will assume that all ADE and Autoware.Core dependencies have been installed.
 
-@note The emulation library used for this section is currently only compatible with `x86_64`.
-Check your system architecture using the following command:
-```{bash}
-$ uname -m
-```
+!!! note
+
+    The emulation library used for this section is currently only compatible with `x86_64`.
+    Check your system architecture using the following command:
+
+    ```{bash}
+    $ uname -m
+    ```
 
 To check the systems which Docker is compatible with run the following command:
+
 ```{bash}
-$ docker buildx ls
+docker buildx ls
 ```
 
 The output the following should look like this:
+
 ```{bash}
 $ docker buildx ls
 NAME/NODE DRIVER/ENDPOINT STATUS  PLATFORMS
 default * docker
-  default default         running linux/amd64, linux/386  
+  default default         running linux/amd64, linux/386
 ```
 
 To check that your system is currently incompatible with `arm64` systems is by running:
+
 ```{bash}
-$ docker run --rm -t arm64v8/ubuntu uname -m
+docker run --rm -t arm64v8/ubuntu uname -m
 ```
+
 The output of this should error and indicate that libraries were not found.
 
 ## Configuring Docker for Multi-architecture Emulation
@@ -74,19 +77,22 @@ architectures.
 The libraries [`qemu`](https://www.qemu.org/) and [`qemu-user-static`](https://github.com/multiarch/qemu-user-static)
 provide emulation support allowing Docker to interpret alternative architectures on an `x86_64` environment.
 The kernel module [`binfmt-support`](http://binfmt-support.nongnu.org/) allows for the registry
-and invocation of binary interpreters at the system administrator level. 
+and invocation of binary interpreters at the system administrator level.
+
 ```{bash}
-$ sudo apt-get install qemu binfmt-support qemu-user-static
+sudo apt-get install qemu binfmt-support qemu-user-static
 ```
 
 Finally, invoke the `qemu-user-static` docker image to install and link the interpreters and
 architectures for various architectures.
+
 ```{bash}
-$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
+docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
 ```
 
 To check that the installation and registry was successful, run the following command and ensure
 that it exits cleanly:
+
 ```{bash}
 $ docker run --rm -t arm64v8/ubuntu uname -m
 ...
@@ -96,19 +102,22 @@ aarch64
 Additional checks include running the `buildx` option with Docker.
 This should output a larger variety of build types available to Docker.
 
-@note There will be an initial warning that the architecture of the image Docker is trying to bring
-up is different to the architecture of the system.
-```{bash}
-WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested
-```
+!!! note
+
+    There will be an initial warning that the architecture of the image Docker is trying to bring up is different to the architecture of the system.
+
+    ```{bash}
+    WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64) and no specific platform was requested
+    ```
 
 ## Launching ADE
 
 Now that the set-up is complete, the `arm64` ADE image can be launched with no issues
+
 ```{bash}
-$ ade --rc .aderc-arm64 start --update --enter
+ade --rc .aderc-arm64 start --update --enter
 ```
 
-@warning Launching ADE in the non-native environment leads to incredibly reduced performance as
-compared to a native configuration due to the binary translation that is happening within Docker;
-approximately 5x that of a native system.
+!!! warning
+
+    Launching ADE in the non-native environment leads to incredibly reduced performance as compared to a native configuration due to the binary translation that is happening within Docker; approximately 5x that of a native system.
diff --git a/docs/installation/installation-ade.md b/docs/installation/installation-ade.md
@@ -1,15 +1,10 @@
-Installation with ADE {#installation-ade}
-=====================
-
-@tableofcontents
-
-# Goals {#installation-and-development-goals}
+# Installation with ADE
 
+## Goals
 
 This article demonstrates how to use the Agile Development Environment (ADE) to develop Autoware.Auto applications.
 
-
-# Install ADE {#installation-and-development-install-ade}
+## Install ADE
 
 [ADE](https://ade-cli.readthedocs.io/en/latest/) is a modular Docker-based tool to ensure that all developers in a project have a common, consistent development environment.
 
@@ -28,22 +23,22 @@ $ ade --version
 <version>
 ```
 
-# Setup ADE home and project checkout {#installation-and-development-setup-ade-home-and-project-checkout}
+## Setup ADE home and project checkout
 
 ADE needs a directory on the host machine which is mounted as the user's
 home directory within the container. The directory is populated with
 dotfiles, and must be different than the user's home directory
-*outside* of the container. In the event ADE is used for multiple, projects it
+_outside_ of the container. In the event ADE is used for multiple, projects it
 is recommended to use dedicated `adehome` directories for each project.
 
 ADE looks for a directory containing a file named `.adehome`
 starting with the current working directory and continuing with the
 parent directories to identify the ADE home directory to be mounted.
 
 ```{bash}
-$ mkdir -p ~/adehome
-$ cd ~/adehome
-$ touch .adehome
+mkdir -p ~/adehome
+cd ~/adehome
+touch .adehome
 ```
 
 For ADE to function, it must be properly configured. Autoware.Auto provides
@@ -54,51 +49,56 @@ overridden by setting environment variables. See the `ade --help` output for mor
 using environment variables to define the configuration.
 
 ```{bash}
-$ cd ~/adehome
-$ git clone https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto.git
+cd ~/adehome
+git clone https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto.git
 ```
 
+TODO: Fix repo url and release url
+
 Checkout the [latest release](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/-/releases) by checking out the corresponding tag or release branch.
 Alternatively, when not checking out any specific tag, the latest `master` branch will be used
 which may include features that are still being developed. For example:
-```
-$ cd AutowareAuto
-$ git checkout tags/1.0.0 -b release-1.0.0
+
+```{bash}
+cd AutowareAuto
+git checkout tags/1.0.0 -b release-1.0.0
 ```
 
-## Sharing files between the host system and ADE (Optional)
+### Sharing files between the host system and ADE (Optional)
+
 It might come in handy to share files such as dotfiles or utility programs from your host machine
 with ADE. If you only have a single `adehome` directory, there is a way to do that without
 duplicating them: move them inside the `adehome` directory, then create a symlink in the host system
 to their regular location. For instance,
 
 ```{bash}
-$ cd ~
-$ cp ~/.bashrc ~/.bashrc.bak
-$ mv ~/.bashrc ~/adehome/.bashrc
-$ ln -s ~/adehome/.bashrc
+cd ~
+cp ~/.bashrc ~/.bashrc.bak
+mv ~/.bashrc ~/adehome/.bashrc
+ln -s ~/adehome/.bashrc
 ```
 
 It will then appear as `~/.bashrc` to the host system and to ADE.
 
 Another option is to put utility programs into `~/adehome/.local/bin` and symlink. The opposite
 direction will not work, files in a Docker container can not be symlinks to the outside.
 
-@note The programs have to be self-contained! They should not depend on loading libraries from e.g.
-`/usr/lib`.
+!!! note
+
+    The programs have to be self-contained! They should not depend on loading libraries from e.g. `/usr/lib`.
 
-@note There is a risk of an error (symlink would be broken and .bashrc would not be loaded when your terminal is started). In this case, you should delete the symlink and move .bashrc back to the original directory.
+    There is a risk of an error (symlink would be broken and .bashrc would not be loaded when your terminal is started). In this case, you should delete the symlink and move .bashrc back to the original directory.
 
-# Entering the development environment
+## Entering the development environment
 
 ```{bash}
-$ cd AutowareAuto
+cd AutowareAuto
 ```
 
 To start the default environment:
 
 ```{bash}
-$ ade start --update --enter
+ade start --update --enter
 ```
 
 There are several preconfigured environments to choose from by specifying an ADE rc file. To see
@@ -120,10 +120,10 @@ Congratulations! Now you should have a terminal inside ADE:
 $ade:~$
 ```
 
-The next steps are to proceed to @ref usage, or to work on the Autoware.Auto code itself as
-described in @ref contributors-guide.
+The next steps are to proceed to [Usage](usage.md), or to work on the Autoware.Code code itself as
+described in [Contributors guide](contributors-guide.md).
 
-# What is where inside ADE?
+## What is where inside ADE?
 
 Upon entering, ADE outputs the images used to create the environment; e.g.
 
@@ -144,34 +144,33 @@ lgsvl        # image: ade-lgsvl/foxy:2020.06
 ros          # image: ade-foxy:master
 ```
 
-The code in `/opt/AutowareAuto` is built from a particular version of the master branch of
-Autoware.Auto. The master branch is built multiple times a day in CI; see the [container
+The code in `/opt/AutowareCore` is built from a particular version of the main branch of
+Autoware.Core. The master branch is built multiple times a day in CI; see the [container
 registry](https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto/container_registry). With
 `ade ... --update`, the latest available version of each image is downloaded.
 
-# Cleanup {#installation-and-development-cleanup}
+## Cleanup
 
 ADE uses Docker, and over time unused images, containers, and volumes begin to clutter the hard
 drive. Follow the steps below to clean the Docker file system of stale images.
 
-
-## Start relevant Docker resources {#installation-and-development-start-relevant-docker-resources}
+### Start relevant Docker resources
 
 First, verify that ADE is running:
 
 ```{bash}
-$ cd ~/adehome/AutowareAuto
-$ ade start
+cd ~/adehome/AutowareAuto
+ade start
 ```
 
 If ADE is used for more than one project, verify all ADE instances are running; the same rule
 applies for any other non-ADE Docker containers that should be preserved.
 
-\note
-Docker resources that are not started/running **will be removed**!
+!!! note
 
+    Docker resources that are not started/running **will be removed**!
 
-## Docker disk usage {#installation-and-development-docker-disk-usage}
+### Docker disk usage
 
 To assess the disk usage situation, run the following command:
 
@@ -184,19 +183,19 @@ Local Volumes       17                  15                  5.411GB
 Build Cache         0                   0                   0B                  0B
 ```
 
-
-## Remove unused docker items {#installation-and-development-remove-unused-docker-items}
+### Remove unused docker items
 
 Use `docker system prune` to remove any Docker items not used for currently running containers:
 
 ```{bash}
-$ docker system prune -a --volumes
+docker system prune -a --volumes
 ```
 
-# Troubleshooting {#ade-troubleshooting}
+## Troubleshooting
+
 Here are solutions for a few specific errors:
 
-## Error - "forward compatibility was attempted on non supported hw" when starting ADE
+### Error - "forward compatibility was attempted on non supported hw" when starting ADE
 
 When starting `ade` with GPU support enabled for NVIDIA graphics, you may sometimes receive the following error:
 
@@ -207,7 +206,7 @@ ERROR: Command return non-zero exit code (see above): 125
 
 This usually indicates that a new NVIDIA graphics driver has been installed (usually via `apt`) but the system has not yet been restarted. A similar message may appear if the graphics driver is not available, for example because of resuming after suspend.
 
-### Solution
+#### Solution
 
 Restart your system after installing the new NVIDIA driver.