diff --git a/README.md b/README.md index e78e02cf0..91ca3db65 100644 --- a/README.md +++ b/README.md @@ -34,4 +34,49 @@ For deploying documentation changes to the web, [Section 3 of rosdoc_lite wiki]( ## Contributing -These tutorials use the same [style guidelines](http://moveit.ros.org/documentation/contributing/code/) as the MoveIt! project. When modifying or adding to these tutorials, it is required that code is auto formatted using [clang-format](http://moveit.ros.org/documentation/contributing/code/). +We rely on the community to keep these tutorials up to date and bug free. If you find an issue with the tutorials please [open an issue on GitHub](https://github.com/ros-planning/moveit_tutorials/issues/new) or open a PR with proposed changes. + +### Formatting and Style + +* These tutorials use the same [style guidelines](http://moveit.ros.org/documentation/contributing/code/) as the MoveIt! project. When modifying or adding to these tutorials, it is required that code is auto formatted using [clang-format](http://moveit.ros.org/documentation/contributing/code/). +* Tutorials should exemplify best coding practices. If a contribution wouldn't pass review in the MoveIt! project, then it shouldn't pass review in the tutorials. +* Each tutorial should be focused on teaching the user one feature or interface within MoveIt!. +* Tutorials should flow from show to tell with videos and demos at the beginning followed by explanations. +* New tutorials should match the formatting, style and flow of existing tutorials whenever possible. +* Relevant code should be included and explained using the ``.. tutorial-formatter::`` tag. +* Irrelevant code should be excluded from the generated html using the ``BEGIN_TUTORIAL``, ``END_TUTORIAL``, ``BEGIN_SUB_TUTORIAL``, and ``END_SUB_TUTORIAL`` tags. +* Whenever possible, links should be created using the ``extlinks`` dictionary defined in ``conf.py``. +* All demo code should be runnable from within the ``moveit_tutorials`` package. +* Python code should be run using ``rosrun``. + +### Directory Structure + +* Each tutorial should live in it's own subdirectory within the `./doc/ <>` directory. +* Tutorials should use the following directory structure omitting unnecessary files and subdirectories: + +``` +moveit_tutorials/doc/ +└── / + ├── _tutorial.rst + ├── CMakeLists.txt + ├── package.xml + ├── setup.py + ├── images/ + │ └── _.png + ├── include/ + │ └── / + │ └── .h # Any custom C++ library header files + ├── launch/ + │ └── _tutorial.launch + ├── src/ + │ ├── _tutorial.cpp # Main C++ executable + │ ├── .cpp # Custom C++ library source files + │ └── / + │ ├── __init__.py + │ ├── _tutorial.py # Main Python executable + │ └── .py # Custom Python libraries + └── test/ # Ideally tutorials have their own integration tests + ├── _tutorial.test # Launch file for tests + ├── _tutorial_test.py # Python tests for tutorial + └── _tutorial_test.cpp # C++ tests for tutorial +``` \ No newline at end of file