Use permalink instead of copy&paste the source code in documents

[fujitatomoya]

trafficstars

It would be really nice and good for maintenance if we can link the source code as permalink instead of doing copy&paste the related source code in this repository.

example: https://github.com/ros2/ros2_documentation/blob/rolling/source/Tutorials/Intra-Process-Communication.rst code-block

[fujitatomoya]

question came up on https://github.com/ros2/ros2_documentation/pull/2441#pullrequestreview-956935799

[kurshakuz]

I agree that it could simplify maintenance a lot! There are already a couple of examples that do use the source code directly in the rst files like:

1. https://github.com/ros2/ros2_documentation/rolling/source/Tutorials/Actions/Writing-a-Cpp-Action-Server-Client.rst
2. https://github.com/ros2/ros2_documentation/blob/rolling/source/Tutorials/Actions/Writing-a-Py-Action-Server-Client.rst

Look for .. literalinclude:: directive.

Unfortunately, those examples require to host code snippets locally. I am not sure if it is possible to directly fetch code samples from other repositories. So I don't think it is a feasible solution. Does anyone have better ideas?

[gavanderhoorn]

Would depending on something like sphinxext-remoteliteralinclude be acceptable for this (Github repository: wpilibsuite/sphinxext-remoteliteralinclude)?

It seems to address the exact issue reported here: be able to retrieve code from a remote location, instead of duplicating it next to the .rst using literalinclude.

[gavanderhoorn]

Put something together using remoteliteralinclude.

See #2828.

[fujitatomoya]

I will go ahead to close this issue, it is gonna be tough to keep the consumable and stable documentation instead of permlink. feel free to reopen this, if someone gets interested.