ODA #107: Create snippet files for single-sourcing repetitive instructions

[nielsenjared]

Description

This PR refers to canonical/open-documentation-academy#107 via @rkratky

It creates reusable snippets for the following docs pages:

• 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

Each snippet corresponds to a section of the page, demarcated by heading. Rather than add comments, I used descriptive file names for the snippets. I established a naming convention for the reuse directory by prepending each .txt file with configure-vm, which could also be a subdirectory. Let me know if you would like me to make any changes.

Checklist

• Runs make check successfully.
• Retains 100% code coverage (make check-coverage).
• New/changed keys in YAML format are documented.
• (Optional) Adds example YAML for new feature.
• (Optional) Closes an open bug in Launchpad.

I didn't run the above checks, but I did run the following per the documentation contribution guide:

• make spelling: returned errors for preexisting words (such as NIC, InterVLAN, netfilter, unconfigured, autostart, etc.)
• make linkcheck: build succeeded
• make woke: returned Error 1 on .gitignore

[slyon]

Thank you very much for your contribution to Netplan!

This is a really nice cleanup, breaking up the big how-to guides into smaller snippets! (CC @ilvipero) I can confirm the rendered output looks identical. Also, all the CI tests are green, so you're local make spelling / make woke issues are fine; some of it got fixed just recently, upstream (e.g. #499).

Some remarks:

• suggestion (non-blocking): I like the new reuse/ directory that you introduced, this builds a nice structure. We might consider renaming it to include/, which is commonly used in code. @rkratky is there any convention around this in docs? For now, we don't need any additional sub-directory for "configure-vm", IMO, sharing a common prefix should be good for now (we might want to change that in the future, once the number of includes grows substantially).
• note (non-blocking): Some of the includes are very small (heading + one line). But this way we're able to reuse most of it, so that's fine.
• question: why did you choose to use a .txt suffix. Those are still markdown snippets after all, shouldn't they end in .md?

Overall, this is looking very good already. I'd like to see a comment about the .txt vs .md, though. And wait for +1 from @rkratky

[rkratky]

suggestion (non-blocking): I like the new reuse/ directory that you introduced, this builds a nice structure. We might consider renaming it to include/, which is commonly used in code. @rkratky is there any convention around this in docs?

For whatever reason, reuse is what the Starter Pack calls it, so I'm fine with it. Though include would be nicer.

note (non-blocking): Some of the includes are very small (heading + one line). But this way we're able to reuse most of it, so that's fine.

I was going to comment on this, too. There's a fine line between efficient single-sourcing and hard-decipher source files. That said, I'm fine with it as it is.

question: why did you choose to use a .txt suffix. Those are still markdown snippets after all, shouldn't they end in .md?

There was a reason for this, but I can't remember what it was :D Something to do with Sphinx, though my memory is really hazy. I'm asking around the docs group. If it turns out it's not a propblem (i.e. having .md files), I'd ask for them to be renamed to have thing intuitive (and syntax-highlighted).

[nielsenjared]

Hey @rkratky & @slyon! Here's some context for the points above:

• I followed the MyST style guide which reads:

Files that only contain text that is reused somewhere else should be placed in the reuse folder and end with the extension .txt to distinguish them from normal content files.

• I created a separate prerequisites snippet for consistency because it spanned all three pages, whereas combining the prerequisite and system sections would only apply to two pages.

Let me know if you need me to make any changes.

[rkratky]

OK, the reason for txt as opposed to md was that Sphinx then auto-excludes the TXT files (we specify only .rst and .md in the config as source files) and doesn't complain either about the file being an orphan or it starting with an out-of-order heading level. This can be prevented by adding the reuse dir in exclude_patterns in conf.py. I'd say it's better than having .txt files.

[slyon]

Thanks for your input @nielsenjared and @rkratky !

I've pushed a commit to move reuse/*.txt to .md files. Other than that, I'm fine with it as-is (keep using reuse/ as used in the starter-pack & having a small prerequisites snippet).

LGTM.