Netplan: Create snippet files for single-sourcing repetitive instructions

[rkratky]

Context

Three of the how-to guides for Netplan feature very similar scenarios, and all of them include certain instructions that are completely the same. In order to simplify maintenance and to ensure consistency, the instructions should be single-sourced from common source. This requires creating a separate file (or files) with these instruction snippets and including them in the how-tos. These are the how-tos:

• How to configure a VM host with a single network interface
• How to configure a VM host with a single network interface and three VLANs
• How to configure a VM host with bonded network interfaces and three VLANs

Task

1. Identify substantial parts of the how-tos that are exactly the same (always at least a section -- not just individual instruction steps or other small parts) and create a separate (.md) files from them. The content needs to be repeated in at least two of the how-tos (if in three, even better).

2. Remove the respective parts from the how-tos and substitute them for include statements that will render the snippets in those places. See Embed & Include Content for instructions on how to do that in Markdown using the MyST extension.

Reference

• Diataxis: Tutorial
• ReadTheDocs: Netplan documentation
• GitHub: netplan

[nielsenjared]

Hey @rkratky! I'm interested in this issue. Is there a timeline for completion?

[rkratky]

Nice @nielsenjared. No real deadline 😌 Of course, it wouldn't be good to block the issue without really intending to work on it. Should I assign it to you?

[nielsenjared]

I'll take it!

…

On Tue, Aug 6, 2024, 15:11 Robert Krátký ***@***.***> wrote: Nice @nielsenjared <https://github.com/nielsenjared>. No real deadline 😌 Of course, it wouldn't be good to block the issue without really intending to work on it. Should I assign it to you? — Reply to this email directly, view it on GitHub <#107 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABPUGB2WW4JVODCPYJ2PKXTZQENULAVCNFSM6AAAAABJWEN5NCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDENZRHE3DKOJYGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[rkratky]

Done and dusted :) Thank you, @nielsenjared!