README.md

March Tutorials

https://project-march.github.io/tutorials/

Welcome to the primary documentation for the March exoskeleton.

These tutorials use the reStructuredText format commonly used in the Sphinx "Python Documentation Generator". This unfortunately differs from the common Markdown format, but its advantage is that it supports embedding code directly from source files for inline code tutorials.

• 
• Documentation on GitHub Pages:

Build Locally

If you want to test the tutorials by generating the html pages locally on your machine, use the build_locally script.

source /opt/ros/$ROS_DISTRO/setup.bash
./build_locally.sh

The local website <LOCAL_PACKAGE_PATH>/build/html/index.html should automatically open in your web browser.

Formatting and Style

Code Formatting

• Tutorials should exemplify best coding practices. If a contribution wouldn't pass review elsewhere, then it shouldn't pass review in the tutorials.
• 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 march_tutorials package.
• Python code should be run using rosrun.

Style

• Each tutorial should be focused on teaching the user one feature or package.
• 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.

Directory Structure

• Each tutorial should live in its own subdirectory within the ./doc/ <> directory.
• Add your tutorial to index.rst in the root directory.
• Tutorials should use the following directory structure omitting unnecessary files and subdirectories:

march_tutorials/doc/
└── <tutorial_name>/
    ├── <tutorial_name>_tutorial.rst
    ├── CMakeLists.txt
    ├── package.xml
    ├── setup.py
    ├── images/
    │   └── <tutorial_name>_<image_description>.png
    ├── include/
    │   └── <tutorial_name>/
    │       └── <include_header>.h                      # Any custom C++ library header files
    ├── launch/
    │   └── <tutorial_name>_tutorial.launch
    ├── src/
    │   ├── <tutorial_name>_tutorial.cpp                # Main C++ executable
    │   ├── <include_source>.cpp                        # Custom C++ library source files
    │   └── <tutorial_name>/
    │       ├── __init__.py
    │       ├── <tutorial_name>_tutorial.py             # Main Python executable
    │       └── <python_library>.py                     # Custom Python libraries
    └── test/                                           # Ideally tutorials have their own integration tests
        ├── <tutorial_name>_tutorial.test               # Launch file for tests
        ├── <tutorial_name>_tutorial_test.py            # Python tests for tutorial
        └── <tutorial_name>_tutorial_test.cpp           # C++ tests for tutorial