update getting started (#1134)

Co-authored-by: Atsushi Sakai <[email protected]>

Author: AtsushiSakai

docs/modules/0_getting_started/2_how_to_run_sample_codes_main.rst

@@ -3,7 +3,21 @@
 How to run sample codes
 -------------------------
 
-1. Clone this repo and go into dir.
+In this chapter, we will explain the setup process for running each sample code
+in PythonRobotics and describe the contents of each directory.
+
+Steps to setup and run sample codes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Install `Python 3.12.x`_
+
+Note that older versions of Python3 might work, but we recommend using
+the specified version, because the sample codes are only tested with it.
+
+2. If you prefer to use conda for package management, install
+Anaconda or Miniconda to use `conda`_ command.
+
+3. Clone this repo and go into dir.
 
 .. code-block::
 
@@ -12,7 +26,10 @@ How to run sample codes
     >$ cd PythonRobotics
 
 
-2. Install the required libraries.
+4. Install the required libraries.
+
+We have prepared requirements management files for `conda`_ and `pip`_ under
+the requirements directory. Using these files makes it easy to install the necessary libraries.
 
 using conda :
 
@@ -27,6 +44,75 @@ using pip :
     >$ pip install -r requirements/requirements.txt
 
 
-3. Execute python script in each directory.
+5. Execute python script in each directory.
+
+For example, to run the sample code of `Extented Kalman Filter` in the
+`localization` directory, execute the following command:
+
+.. code-block::
+
+    >$ cd localization/extended_kalman_filter
+
+	>$ python extended_kalman_filter.py
+
+Then, you can see this animation of the EKF algorithm based localization:
+
+.. image:: https://github.com/AtsushiSakai/PythonRoboticsGifs/raw/master/Localization/extended_kalman_filter/animation.gif
+
+Please refer to the `Directory structure`_ section for more details on the contents of each directory.
+
+6. Add star to this repo if you like it 😃.
+
+.. _`Python 3.12.x`: https://www.python.org/
+.. _`conda`: https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html
+.. _`pip`: https://pip.pypa.io/en/stable/
+.. _`the requirements directory`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/requirements
+
+.. _`Directory structure`:
+
+Directory structure
+~~~~~~~~~~~~~~~~~~~~
+
+The top-level directory structure of PythonRobotics is as follows:
+
+Sample codes directories:
+
+- `AerialNavigation`_ : the sample codes of aerial navigation algorithms for drones and rocket landing.
+- `ArmNavigation`_ : the sample codes of arm navigation algorithms for robotic arms.
+- `Localization`_ : the sample codes of localization algorithms.
+- `Bipedal`_ : the sample codes of bipedal walking algorithms for legged robots.
+- `Control`_ : the sample codes of control algorithms for robotic systems.
+- `Mapping`_ : the sample codes of mapping or obstacle shape recognition algorithms.
+- `PathPlanning`_ : the sample codes of path planning algorithms.
+- `PathTracking`_ : the sample codes of path tracking algorithms for car like robots.
+- `SLAM`_ : the sample codes of SLAM algorithms.
+
+Other directories:
+
+- `docs`_ : This directory contains the documentation of PythonRobotics.
+- `requirements`_ : This directory contains the requirements management files.
+- `tests`_ : This directory contains the unit test files.
+- `utils`_ : This directory contains utility functions used in some sample codes in common.
+- `.github`_ : This directory contains the GitHub Actions configuration files.
+- `.circleci`_ : This directory contains the CircleCI configuration files.
+
+The structure of this document is the same as that of the sample code
+directories mentioned above.
+For more details, please refer to the :ref:`How to read this textbook` section.
+
 
-4. Add star to this repo if you like it 😃.
+.. _`AerialNavigation`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/AerialNavigation
+.. _`ArmNavigation`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/ArmNavigation
+.. _`Localization`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/Localization
+.. _`Bipedal`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/Bipedal
+.. _`Control`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/Control
+.. _`Mapping`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/Mapping
+.. _`PathPlanning`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/PathPlanning
+.. _`PathTracking`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/PathTracking
+.. _`SLAM`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/SLAM
+.. _`docs`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/docs
+.. _`requirements`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/requirements
+.. _`tests`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/tests
+.. _`utils`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/utils
+.. _`.github`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/.github
+.. _`.circleci`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/.circleci