update getting started (#1132)

docs/modules/0_getting_started/0_getting_started_main.rst

@@ -0,0 +1,13 @@
+.. _`getting started`:
+
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   1_what_is_python_robotics
+   2_how_to_use
+   3_how_to_contribute
+   4_how_to_read_textbook

docs/modules/0_getting_started/1_what_is_python_robotics_main.rst

@@ -0,0 +1,109 @@
+.. _`What is PythonRobotics?`:
+
+What is PythonRobotics?
+------------------------
+
+This is an Open Source Software (OSS) project: PythonRobotics, which is a Python code collection of robotics algorithms.
+These codes are developed under `MIT license`_ and on `GitHub`_.
+
+This project has three main philosophies below:
+
+Philosophy 1. Easy to understand each algorithm's basic idea.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The goal is for beginners in robotics to understand the basic ideas behind each algorithm.
+
+`Python`_ programming language is adopted in this project to achieve the goal.
+Python is a high-level programming language that is easy to read and write.
+If the code is not easy to read, it would be difficult to achieve our goal of
+allowing beginners to understand the algorithms.
+Python has great libraries for matrix operation, mathematical and scientific operation,
+and visualization, which makes code more readable because such operations
+don’t need to be re-implemented.
+Having the core Python packages allows the user to focus on the algorithms,
+rather than the implementations.
+
+PythonRobotics provides not only the code but also intuitive animations that
+visually demonstrate the process and behavior of each algorithm over time.
+This is an example of an animation gif file that shows the process of the
+path planning in a highway scenario for autonomous vehicle.
+
+.. image:: https://github.com/AtsushiSakai/PythonRoboticsGifs/raw/master/PathPlanning/FrenetOptimalTrajectory/high_speed_and_velocity_keeping_frenet_path.gif
+
+This animation is a gif file and is created using the `Matplotlib`_ library.
+All animation gif files are stored in the `PythonRoboticsGifs`_ repository and
+all animation movies are also uploaded to this `YouTube channel`_.
+
+PythonRobotics also provides a textbook that explains the basic ideas of each algorithm.
+The PythonRobotics textbook allows you to learn fundamental algorithms used in
+robotics with minimal mathematical formulas and textual explanations,
+based on PythonRobotics’ sample codes and animations.
+The contents of this document, like the code, are managed in the PythonRobotics
+`GitHub`_ repository and converted into HTML-based online documents using `Sphinx`_,
+which is a Python-based documentation builder.
+Please refer to this section ":ref:`How to read this textbook`" for information on
+how to read this document for learning.
+
+
+.. _`Python`: https://www.python.org/
+.. _`PythonRoboticsGifs`: https://github.com/AtsushiSakai/PythonRoboticsGifs
+.. _`YouTube channel`: https://youtube.com/playlist?list=PL12URV8HFpCozuz0SDxke6b2ae5UZvIwa&si=AH2fNPPYufPtK20S
+
+
+Philosophy 2. Widely used and practical algorithms are selected.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The second philosophy is that implemented algorithms have to be practical
+and widely used in both academia and industry.
+We believe learning these algorithms will be useful in many applications.
+For example, Kalman filters and particle filter for localization,
+grid mapping for mapping,
+dynamic programming based approaches and sampling based approaches for path planning,
+and optimal control based approach for path tracking.
+These algorithms are implemented in this project.
+
+Philosophy 3. Minimum dependency.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each sample code is written in Python3 and only depends on some standard
+modules for readability and ease of use.
+
+
+.. _GitHub: https://github.com/AtsushiSakai/PythonRobotics
+.. _`MIT license`: https://github.com/AtsushiSakai/PythonRobotics/blob/master/LICENSE
+
+
+See this paper for more details:
+
+- PythonRobotics: a Python code collection of robotics algorithms: https://arxiv.org/abs/1808.10703
+
+.. _`Requirements`:
+
+Requirements
+============
+
+-  `Python 3.12.x`_
+-  `NumPy`_
+-  `SciPy`_
+-  `Matplotlib`_
+-  `cvxpy`_
+
+For development:
+
+-  `pytest`_ (for unit tests)
+-  `pytest-xdist`_ (for parallel unit tests)
+-  `mypy`_ (for type check)
+-  `Sphinx`_ (for document generation)
+-  `ruff`_ (for code style check)
+
+.. _`Python 3.12.x`: https://www.python.org/
+.. _`NumPy`: https://numpy.org/
+.. _`SciPy`: https://scipy.org/
+.. _`Matplotlib`: https://matplotlib.org/
+.. _`cvxpy`: https://www.cvxpy.org/
+.. _`pytest`: https://docs.pytest.org/en/latest/
+.. _`pytest-xdist`: https://github.com/pytest-dev/pytest-xdist
+.. _`mypy`: https://mypy-lang.org/
+.. _`Sphinx`: https://www.sphinx-doc.org/en/master/index.html
+.. _`ruff`: https://github.com/astral-sh/ruff
+

docs/modules/0_getting_started/2_how_to_use_main.rst

@@ -0,0 +1,30 @@
+How to use
+----------
+
+1. Clone this repo and go into dir.
+
+.. code-block::
+
+    >$ git clone https://github.com/AtsushiSakai/PythonRobotics.git
+
+    >$ cd PythonRobotics
+
+
+2. Install the required libraries.
+
+using conda :
+
+.. code-block::
+
+    >$ conda env create -f requirements/environment.yml
+
+using pip :
+
+.. code-block::
+
+    >$ pip install -r requirements/requirements.txt
+
+
+3. Execute python script in each directory.
+
+4. Add star to this repo if you like it 😃.

docs/modules/0_getting_started/3_how_to_contribute_main.rst

@@ -0,0 +1,164 @@
+How To Contribute
+=================
+
+This document describes how to contribute this project.
+
+Adding a new algorithm example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is a step by step manual to add a new algorithm example.
+
+Step 1: Choose an algorithm to implement
+-----------------------------------------
+
+Before choosing an algorithm, please check the :ref:`getting started` doc to
+understand this project's philosophy and setup your development environment.
+
+If an algorithm is widely used and successful, let's create an issue to
+propose it for our community.
+
+If some people agree by thumbs up or posting positive comments, let go to next step.
+
+It is OK to just create an issue to propose adding an algorithm, someone might implement it.
+
+In that case, please share any papers or documentations to implement it.
+
+
+Step 2: Implement the algorithm with matplotlib based animation
+----------------------------------------------------------------
+
+When you implement an algorithm, please keep the following items in mind.
+
+1. Use only Python. Other language code is not acceptable.
+
+2. This project only accept codes for python 3.9 or higher.
+
+3. Use matplotlib based animation to show how the algorithm works.
+
+4. Only use current :ref:`Requirements` libraries, not adding new dependencies.
+
+5. Keep simple your code. The main goal is to make it easy for users to understand the algorithm, not for practical usage.
+
+
+Step 3: Add a unittest
+----------------------
+If you add a new algorithm sample code, please add a unit test file under `tests dir`_.
+
+This sample test code might help you : `test_a_star.py`_.
+
+At the least, try to run the example code without animation in the unit test.
+
+If you want to run the test suites locally, you can use the `runtests.sh` script by just executing it.
+
+The `test_codestyle.py`_ check code style for your PR's codes.
+
+
+.. _`how to write doc`:
+
+Step 4: Write a document about the algorithm
+----------------------------------------------
+Please add a document to describe the algorithm details, mathematical backgrounds and show graphs and animation gif.
+
+This project is using `Sphinx`_ as a document builder, all documentations are written by `reStructuredText`_.
+
+You can add a new rst file under the subdirectory in `doc modules dir`_ and the top rst file can include it.
+
+Please check other documents for details.
+
+You can build the doc locally based on `doc README`_.
+
+Note that the `reStructuredText`_ based doc should only focus on the mathematics and the algorithm of the example.
+
+Documentations related codes should be in the python script as the header comments of the script or docstrings of each function.
+
+
+.. _`submit a pull request`:
+
+Step 5: Submit a pull request and fix codes based on review
+------------------------------------------------------------
+
+Let's submit a pull request when your code, test, and doc are ready.
+
+At first, please fix all CI errors before code review.
+
+You can check your PR doc from the CI panel.
+
+After the "ci/circleci: build_doc" CI is succeeded,
+you can access you PR doc with clicking the [Details] of the "ci/circleci: build_doc artifact" CI.
+
+.. image:: /_static/img/doc_ci.png
+
+After that, I will start the review.
+
+Note that this is my hobby project; I appreciate your patience during the review process.
+
+
+Reporting and fixing a defect
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Reporting and fixing a defect is also great contribution.
+
+When you report an issue, please provide these information:
+
+- A clear and concise description of what the bug is.
+- A clear and concise description of what you expected to happen.
+- Screenshots to help explain your problem if applicable.
+- OS version
+- Python version
+- Each library versions
+
+If you want to fix any bug, you can find reported issues in `bug labeled issues`_.
+
+If you fix a bug of existing codes, please add a test function
+in the test code to show the issue was solved.
+
+This doc `submit a pull request`_ can be helpful to submit a pull request.
+
+
+Adding missed documentations for existing examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Adding the missed documentations for existing examples is also great contribution.
+
+If you check the `Python Robotics Docs`_, you can notice that some of the examples
+only have a simulation gif or short overview descriptions,
+but no detailed algorithm or mathematical description.
+
+This doc `how to write doc`_ can be helpful to write documents.
+
+Supporting this project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Supporting this project financially is also a great contribution!!.
+
+If you or your company would like to support this project, please consider:
+
+- `Sponsor @AtsushiSakai on GitHub Sponsors`_
+
+- `Become a backer or sponsor on Patreon`_
+
+- `One-time donation via PayPal`_
+
+If you would like to support us in some other way, please contact with creating an issue.
+
+Sponsors
+---------
+
+1. `JetBrains`_ : They are providing a free license of their IDEs for this OSS development.
+
+
+.. _`Python Robotics Docs`: https://atsushisakai.github.io/PythonRobotics
+.. _`bug labeled issues`: https://github.com/AtsushiSakai/PythonRobotics/issues?q=is%3Aissue+is%3Aopen+label%3Abug
+.. _`tests dir`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/tests
+.. _`test_a_star.py`: https://github.com/AtsushiSakai/PythonRobotics/blob/master/tests/test_a_star.py
+.. _`Sphinx`: https://www.sphinx-doc.org/
+.. _`reStructuredText`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _`doc modules dir`: https://github.com/AtsushiSakai/PythonRobotics/tree/master/docs/modules
+.. _`doc README`: https://github.com/AtsushiSakai/PythonRobotics/blob/master/docs/README.md
+.. _`test_codestyle.py`: https://github.com/AtsushiSakai/PythonRobotics/blob/master/tests/test_codestyle.py
+.. _`JetBrains`: https://www.jetbrains.com/
+.. _`Sponsor @AtsushiSakai on GitHub Sponsors`: https://github.com/sponsors/AtsushiSakai
+.. _`Become a backer or sponsor on Patreon`: https://www.patreon.com/myenigma
+.. _`One-time donation via PayPal`: https://www.paypal.com/paypalme/myenigmapay/
+
+

docs/modules/0_getting_started/4_how_to_read_textbook_main.rst

@@ -0,0 +1,6 @@
+.. _`How to read this textbook`:
+
+How to read this textbook
+--------------------------
+
+TBD