Proposal: Supporting literate programming for `msg` files for improved documentation

I am not sure if this has been discussed, but I would like to propose supporting literate programming with interfaces files (.msg, .srv, .action). The example of literate programming I am thinking of is from emacs org-mode (How to Use Emacs Org-Babel Mode to Write Literate Programming Document in R Language).

I see that most message files have comments providing documentation (for example common_interfaces/Plane.msg at rolling · ros2/common_interfaces · GitHub) and using a literate programming approach would allow for nice looking documentation when browsing source on github and gitlab hosted files. This would help with SEO and could help improve the quality of documentation. The readme at common_interfaces/README.md at rolling · ros2/common_interfaces · GitHub already links to .msg files and the experience would be better if those files could also be rendered in HTML by github instead of as a raw text document. Also, even reading the files in a text editor, it will be easier to read documentation if it does not all need to be commented out with #.

At a high level I propose the following:

  • Select a markup language to use, such as markdown or reStructuredText (Or support multiple)
  • Add support for files that end in .msg.md, .src.md and .msg.action when using markdown
  • Parse the file for all code blocks that correspond to the file extension and concatenate them to produce a “tangled” file for further msg/srv/action generation.

For example, in a file "my_message.msg.md", the first two code blocks will be parsed because the code block language and file extension both are msg and the third code block will not be parsed because the code block language and the file extension don’t match.

# My Message
## Fields
* The `data` member holds an integer.
  ```msg
  std_msgs/msg/Int32 data
  ```
* The `str` member holds an optional string.
  ```msg
  std_msgs/msg/String str
  ```
## See also
The `result_val` in `MyService` also has the same semantic meaning as the `data` field in `MyMessage` although the inclusion of this code block is probably more of an edge case than something that will be commonly used.
```srv
# ...
---
# ...
std_msgs/msg/Int32 result_val
```

When the above my_message.msg.md is processed it is tangled to create the following content which is then further processed as any other .msg file content for message generation.

std_msgs/msg/Int32 data
std_msgs/msg/String str
1 Like