Documentation improvements (Diátaxis) (FR-2276)

[slyon]

Description

Re-structuring of Netplan's documentation, according to Diátaxis
The primary documentation (YAML config reference) has been refactored, making use of standard Markdown syntax (instead of pandoc specialities), to be able to render to other frontends like Sphinx or Discourse.

This can now be rendered to several frontends (keeping compatibility with old manpages/pandoc):

• ReadTheDocs: https://canonical-netplan.readthedocs-hosted.com/en/latest/
• ReadTheDocs (Community): https://netplan.readthedocs.io
• Sphinx: https://people.ubuntu.com/~slyon/netplan-docs
• GitHub: doc/netplan-yaml.md#introduction
• Man pages (pandoc)
• Pandoc HTML: https://people.ubuntu.com/~slyon/netplan-docs/netplan.html
• Discourse: https://netplan-io-233.demos.haus/docs/Reference

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.

[sil2100]

Ok, I think this looks good. I am not completely sure about if this fully follows Diataxis ideology, but at least it feels structured properly. We might want to ask Daniele for a sign off - but that could be done after this PR is done (no need to block on that).

I like this direction in overall, because this means we'll have all of the documentation bits in one repository (not having to worry about the netplan.io one having contents we have no control over). I see you moved things like the examples section into the netplan docs here.

A bit that's a bit confusing to me is the meson doc situation. I mean, I understand the situation: when we build netplan with meson we care about manpages, and the meson.build in doc creates manpages with pandoc. But it gets a bit confusing, because you just have to use the Makefile there to get any other output. It's okay, but it feels a bit disconnected. That being said, not a real problem.

[slyon]

Ok, I think this looks good. I am not completely sure about if this fully follows Diataxis ideology, but at least it feels structured properly. We might want to ask Daniele for a sign off - but that could be done after this PR is done (no need to block on that).

Thanks for your review! I'm not a Diataxis expert by any means myself, but I tried to move the existing documentation roughly into the Diataxis categories. IMO, fine-tuning those can be an iterative process after we land the initial structure (i.e. this PR).

I like this direction in overall, because this means we'll have all of the documentation bits in one repository (not having to worry about the netplan.io one having contents we have no control over). I see you moved things like the examples section into the netplan docs here.

Yes, I copied over the examples page from https://netplan.io/examples as there has been some confusion about https://netplan.io/examples vs https://github.com/canonical/netplan/tree/main/examples in the past, which we can cover better if we track the examples page as part of the documentation (and maybe converge the two locations in the future).

OTOH, I've also added some hyperlinks to external documents under Tutorials, API specification and Explanation (e.g. https://netplan.io/design & https://netplan.io/faq) as I did not want to hijack all of the netplan.io website and drag it into the Documentation, although that might make sense. I guess that's something to be discussed with Daniele.

A bit that's a bit confusing to me is the meson doc situation. I mean, I understand the situation: when we build netplan with meson we care about manpages, and the meson.build in doc creates manpages with pandoc. But it gets a bit confusing, because you just have to use the Makefile there to get any other output. It's okay, but it feels a bit disconnected. That being said, not a real problem.

Indeed, the doc/Makefile is completely detached from the overall official build process of ./Makefile (old) or meson.build (new). That is because it is only to be used to set up a local development environment (i.e. Sphinx environment) to actively work on the docs, but does not produce any artifacts which would be shipped or deployed (at least for now). We might be able to consolidate this, by either getting rid of it, or integrating it with the official meson build process (using proper Sphinx distro dependencies, instead of a Python venv), once we agreed upon which tool to use for that.

I've added a comment about this at the top of doc/Makefile to clarify this situation a bit (via 93446c1), but would merge it as-is for now.