How do you document and share your Python code for robot programming?

1 Use docstrings and comments

Docstrings and comments are essential for explaining the purpose, functionality, and logic of your code. Docstrings are multi-line strings that describe a module, class, function, or method. They are usually placed at the beginning of the code block and can be accessed by the help() function or other documentation tools. Comments are single-line or multi-line strings that start with # and are ignored by the interpreter. They are used to clarify specific lines or sections of code. For example:

# This is a comment
def move_forward(distance):
    """This is a docstring
    This function moves the robot forward by a given distance in meters
    """
    # This is another comment
    speed = 0.5 # speed in m/s
    time = distance / speed # time in seconds
    # Send commands to the robot
    robot.set_speed(speed)
    robot.set_direction(0)
    robot.move(time)        

2 Follow PEP 8 and PEP 257

PEP 8 and PEP 257 are official style guides for Python code and docstrings, respectively. They provide recommendations and conventions for formatting, naming, spacing, indentation, and other aspects of writing clean and consistent code. Following these guidelines will make your code more readable, maintainable, and compatible with other Python tools and libraries. You can use tools like pylint, flake8, or black to check and format your code according to PEP 8 and PEP 257.

3 Use Sphinx and Read the Docs

Sphinx and Read the Docs are powerful tools for generating and hosting online documentation for your Python code. Sphinx is a documentation generator that can extract information from your docstrings, comments, and source code, and create HTML, PDF, or other formats of documentation. You can also customize the appearance, structure, and content of your documentation with themes, extensions, and markup languages. Read the Docs is a platform that can host your Sphinx documentation for free, and automatically update it whenever you push changes to your code repository.

5 Use Jupyter Notebook and Binder

Jupyter Notebook and Binder are interactive tools for creating and sharing Python code for robot programming with live examples, visualizations, and explanations. Jupyter Notebook is a web-based application that allows you to write, run, and document your code in cells that can contain text, code, or output. You can also use Jupyter Notebook to connect to your robot and control it with Python commands. Binder is a service that allows you to launch and run your Jupyter Notebook online from a GitHub repository, without installing anything on your local machine.

6 Use ROS and rosbag

ROS and rosbag are useful tools for communicating and recording data from your robot with Python code. ROS (Robot Operating System) is a framework that provides libraries, tools, and protocols for developing and running robot applications. ROS uses a distributed architecture of nodes that communicate with each other through topics, services, or actions. You can use Python to write ROS nodes that send or receive messages from your robot or other nodes. rosbag is a tool that allows you to record and play back ROS messages from topics. You can use rosbag to save and share data from your robot experiments or simulations.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?