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
orreStructuredText
(Or support multiple) - Add support for files that end in
.msg.md
,.src.md
and.msg.action
when usingmarkdown
- 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