diff --git a/README.md b/README.md index 024c600c..195eb1bd 100644 --- a/README.md +++ b/README.md @@ -96,17 +96,17 @@ See this paper for more details: For running each sample code: -- Python 3.9.x +- [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/) -- numpy - -- scipy - -- matplotlib - -- pandas - -- [cvxpy](https://www.cvxpy.org/index.html) +- [cvxpy](https://www.cvxpy.org/) For development: diff --git a/docs/README.md b/docs/README.md index 728a8129..5c4145e8 100644 --- a/docs/README.md +++ b/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/ diff --git a/docs/_static/img/doc_ci.png b/docs/_static/img/doc_ci.png new file mode 100644 index 00000000..a9a73f7e Binary files /dev/null and b/docs/_static/img/doc_ci.png differ diff --git a/docs/getting_started_main.rst b/docs/getting_started_main.rst index 83565eb8..d907ab86 100644 --- a/docs/getting_started_main.rst +++ b/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. diff --git a/docs/how_to_contribute_main.rst b/docs/how_to_contribute_main.rst new file mode 100644 index 00000000..e0007854 --- /dev/null +++ b/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 + diff --git a/docs/index_main.rst b/docs/index_main.rst index 978c216f..7cdbddc7 100644 --- a/docs/index_main.rst +++ b/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 diff --git a/docs/modules/introduction_main.rst b/docs/modules/introduction_main.rst index e9fce334..60cb085a 100644 --- a/docs/modules/introduction_main.rst +++ b/docs/modules/introduction_main.rst @@ -2,5 +2,4 @@ Introduction ============ -Ref ---- +TBD \ No newline at end of file