Add how to contribute docs (#573)

* clean up SLAM docs

* clean up SLAM docs

* clean up SLAM docs

* clean up SLAM docs

* add contribution doc

* add contribution doc

* add contribution doc

* add contribution doc

* add contribution doc

docs/README.md

@@ -24,3 +24,6 @@ if you want to building each time a file is changed:
 sphinx-autobuild . _build/html
 ```
 
+#### Check the generated doc
+
+Open the index.html file under docs/_build/

docs/getting_started_main.rst

@@ -1,4 +1,4 @@
-.. _getting_started:
+.. _`getting started`:
 
 Getting Started
 ===============
@@ -21,27 +21,60 @@ See this paper for more details:
 
 - PythonRobotics: a Python code collection of robotics algorithms: https://arxiv.org/abs/1808.10703
 
+.. _`Requirements`:
 
 Requirements
 -------------
 
--  Python 3.9.x
--  numpy
--  scipy
--  matplotlib
--  pandas
+-  `Python 3.9.x`_
+-  `NumPy`_
+-  `SciPy`_
+-  `Matplotlib`_
+-  `pandas`_
 -  `cvxpy`_
 
-.. _cvxpy: http://www.cvxpy.org/en/latest/
+For development:
+
+-  pytest (for unit tests)
+-  pytest-xdist (for parallel unit tests)
+-  mypy (for type check)
+-  sphinx (for document generation)
+-  pycodestyle (for code style check)
+
+.. _`Python 3.9.x`: https://www.python.org/
+.. _`NumPy`: https://numpy.org/
+.. _`SciPy`: https://scipy.org/
+.. _`Matplotlib`: https://matplotlib.org/
+.. _`pandas`: https://pandas.pydata.org/
+.. _`cvxpy`: https://www.cvxpy.org/
 
 
 How to use
 ----------
 
-1. Install the required libraries. You can use environment.yml with
-   conda command.
+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 environment.yml
+
+using pip :
+
+.. code-block::
+
+    >$ pip install -r requirements.txt
 
-2. Clone this repo.
 
 3. Execute python script in each directory.
 

docs/how_to_contribute_main.rst

@@ -0,0 +1,129 @@
+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.
+
+
+.. _`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`_.
+
+
+.. _`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.
+
+.. _`Python Robotics Docs`: https://pythonrobotics.readthedocs.io/en/latest/
+.. _`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
+

docs/index_main.rst

@@ -43,6 +43,7 @@ See this paper for more details:
    modules/arm_navigation/arm_navigation
    modules/aerial_navigation/aerial_navigation
    modules/appendix/appendix
+   how_to_contribute
 
 
 Indices and tables

docs/modules/introduction_main.rst

@@ -2,5 +2,4 @@
 Introduction
 ============
 
-Ref
----
+TBD