Fix docs directory structure to reflect diátaxis

.gitignore

@@ -10,3 +10,4 @@ __pycache__
 src/_features.h
 netplan_cli/_features.py
 dbus/io.netplan.Netplan.service
+.DS_Store

doc/.sphinx/spellingcheck.yaml

@@ -9,7 +9,7 @@ matrix:
     - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
   sources:
-  - _build/**/*.html|!_build/genindex/index.html|!_build/apidoc/**/*.html
+  - _build/**/*.html|!_build/genindex/index.html|!_build/reference/apidoc/**/*.html
   pipeline:
   - pyspelling.filters.html:
       comments: false

doc/conf.py

@@ -120,8 +120,10 @@
 # For example: 'explanation/old-name.html': '../how-to/prettify.html',
 
 redirects = {
-    'README.md': '/',
-    'netplan': '/netplan-yaml',
+    'README.md': '../',
+    'netplan': '../reference/netplan-yaml',
+    'netplan-everywhere': '../howto/netplan-everywhere',
+    'netplan-yaml': '../reference/netplan-yaml',
 }
 
 ############################################################

doc/security.md → doc/explanation/security.md

@@ -61,7 +61,7 @@ varying key lengths of RSA, DSA, ECDSA, ECDH and EdDSA.
 ### Cryptographic technology exposed to the user
 
 Netplan allows to configure certain cryptographic technology that can be
-described in its {doc}`netplan-yaml`. Notable settings include the
+described in its {doc}`../reference/netplan-yaml`. Notable settings include the
 {ref}`yaml-auth` block, e.g. `auth.password` can be used configure `WPA-PSK` or
 `WPA-EAP` secrets, which can also be a special `hash:...` value for
 `wpa_supplicant`. The `auth.method` field controls the technology, such as

doc/multi-nic-vm-host-with-bonds-and-vlans.md → doc/howto/multi-nic-vm-host-with-bonds-and-vlans.md

@@ -3,7 +3,7 @@
 This guide shows how to configure a virtual machine (VM) host using Netplan and the `virsh` interface. The host in this scenario has four network interface (NICs). The host uses network bonding and three VLAN networks.
 
 
-```{include} reuse/configure-vm-prerequisites.md
+```{include} ../reuse/configure-vm-prerequisites.md
 
 ```
 
@@ -35,7 +35,7 @@ This guide shows how to configure a virtual machine (VM) host using Netplan and
 - Firewall configured; see [UFW](https://help.ubuntu.com/community/UFW).
 
 
-```{include} reuse/configure-vm-disable-netfilter.md
+```{include} ../reuse/configure-vm-disable-netfilter.md
 
 ```
 
@@ -141,16 +141,16 @@ Configure Netplan:
     ```
 
 
-```{include} reuse/configure-vm-using-virsh.md
+```{include} ../reuse/configure-vm-using-virsh.md
 
 ```
 
 
-```{include} reuse/configure-vm-check-networking-delete-default.md
+```{include} ../reuse/configure-vm-check-networking-delete-default.md
 
 ```
 
 
-```{include} reuse/configure-vm-create-bridged-networks.md
+```{include} ../reuse/configure-vm-create-bridged-networks.md
 
 ```

doc/single-nic-vm-host-with-vlans.md → doc/howto/single-nic-vm-host-with-vlans.md

@@ -3,12 +3,12 @@
 This guide shows how to configure a virtual machine (VM) host using Netplan and the `virsh` interface. The host in this scenario has a single network interface (NIC) and three VLAN networks.
 
 
-```{include} reuse/configure-vm-prerequisites.md
+```{include} ../reuse/configure-vm-prerequisites.md
 
 ```
 
 
-```{include} reuse/configure-vm-prerequisites-system.md
+```{include} ../reuse/configure-vm-prerequisites-system.md
 
 ```
 
@@ -29,7 +29,7 @@ This guide shows how to configure a virtual machine (VM) host using Netplan and
 - Firewall configured; see [UFW](https://help.ubuntu.com/community/UFW).
 
 
-```{include} reuse/configure-vm-disable-netfilter.md
+```{include} ../reuse/configure-vm-disable-netfilter.md
 
 ```
 
@@ -118,16 +118,16 @@ Configure Netplan:
     ```
 
 
-```{include} reuse/configure-vm-using-virsh.md
+```{include} ../reuse/configure-vm-using-virsh.md
 
 ```
 
 
-```{include} reuse/configure-vm-check-networking-delete-default.md
+```{include} ../reuse/configure-vm-check-networking-delete-default.md
 
 ```
 
 
-```{include} reuse/configure-vm-create-bridged-networks.md
+```{include} ../reuse/configure-vm-create-bridged-networks.md
 
 ```

doc/single-nic-vm-host.md → doc/howto/single-nic-vm-host.md

@@ -3,12 +3,12 @@
 This guide shows how to configure a virtual-machine host using Netplan and the `virsh` interface. The host in this scenario has a single network interface.
 
 
-```{include} reuse/configure-vm-prerequisites.md
+```{include} ../reuse/configure-vm-prerequisites.md
 
 ```
 
 
-```{include} reuse/configure-vm-prerequisites-system.md
+```{include} ../reuse/configure-vm-prerequisites-system.md
 
 ```
 
@@ -26,7 +26,7 @@ This guide shows how to configure a virtual-machine host using Netplan and the `
 - Firewall configured; see [UFW](https://help.ubuntu.com/community/UFW).
 
 
-```{include} reuse/configure-vm-disable-netfilter.md
+```{include} ../reuse/configure-vm-disable-netfilter.md
 
 ```
 
@@ -81,12 +81,12 @@ Configure Netplan:
     ```
 
 
-```{include} reuse/configure-vm-using-virsh.md
+```{include} ../reuse/configure-vm-using-virsh.md
 
 ```
 
 
-```{include} reuse/configure-vm-check-networking-delete-default.md
+```{include} ../reuse/configure-vm-check-networking-delete-default.md
 
 ```
 

doc/index.md

@@ -1,14 +1,13 @@
 # Netplan documentation
 
 ```{toctree}
----
-maxdepth: 2
-hidden: true
----
-tutorial
-howto
-reference
-explanation
+:maxdepth: 2
+:hidden: true
+
+tutorial/index
+howto/index
+reference/index
+explanation/index
 ```
 
 **Netplan** is a network configuration abstraction renderer.
@@ -27,14 +26,14 @@ systemd-networkd.
 
 ::::{grid} 1 1 2 2
 
-:::{grid-item-card} **[Tutorial](/netplan-tutorial)**
-:link: /netplan-tutorial
+:::{grid-item-card} **[Tutorial](tutorial/netplan-tutorial)**
+:link: tutorial/netplan-tutorial
 :link-type: doc
 
 **Get started** - hands-on introduction to Netplan for new users
 :::
-:::{grid-item-card} **[How-to guides](/examples)**
-:link: /examples
+:::{grid-item-card} **[How-to guides](howto/examples)**
+:link: howto/examples
 :link-type: doc
 
 **Step-by-step guides** covering key operations and common tasks
@@ -44,14 +43,14 @@ systemd-networkd.
 ::::{grid} 1 1 2 2
 :reverse:
 
-:::{grid-item-card} **[Reference](/reference)**
-:link: /reference
+:::{grid-item-card} **[Reference](reference/index)**
+:link: reference/index
 :link-type: doc
 
 **Technical information** - specifications, APIs, architecture
 :::
-:::{grid-item-card} **[Explanation](/explanation)**
-:link: /explanation
+:::{grid-item-card} **[Explanation](explanation/index)**
+:link: explanation/index
 :link-type: doc
 
 **Discussion and clarification** of key topics

doc/meson.build

@@ -1,12 +1,12 @@
 if pandoc.found()
     custom_target(
-        input: ['manpage-header.md', 'structure-id.md', 'netplan-yaml.md', 'manpage-footer.md'],
+        input: ['manpage-header.md', 'explanation/structure-id.md', 'reference/netplan-yaml.md', 'manpage-footer.md'],
         output: 'netplan.5',
         command: [pandoc, '-s', '-o', '@OUTPUT@', '--from=markdown-smart', '@INPUT@'],
         install: true,
         install_dir: join_paths(get_option('mandir'), 'man5'))
     custom_target(
-        input: 'netplan-yaml.md',
+        input: 'reference/netplan-yaml.md',
         output: 'netplan.html',
         command: [pandoc, '-s', '--metadata', 'title="Netplan reference"', '--toc', '-o', '@OUTPUT@', '@INPUT@'],
         install: true,
@@ -15,7 +15,7 @@ if pandoc.found()
       'netplan-apply', 'netplan-dbus', 'netplan-generate', 'netplan-get', 'netplan-set',
       'netplan-try', 'netplan-info', 'netplan-ip', 'netplan-status', 'netplan-rebind',
       ]
-        markdown = files(doc + '.md')
+        markdown = files('reference/' + doc + '.md')
         manpage = doc + '.8'
         custom_target(
             input: markdown,

doc/netplan-yaml.md → doc/reference/netplan-yaml.md

@@ -2192,4 +2192,4 @@ consumer of that back end. Currently, this is only used with `NetworkManager`.
 
     > Can be used as a fallback mechanism to missing key-file settings.
 
-<!--- vim: ft=markdown -->
+<!--- vim: ft=markdown -->

tests/validate_docs.sh

@@ -17,12 +17,12 @@ fi
 for term in $(sed -n 's/[ ]\+{"\([a-z0-9-]\+\)", YAML_[A-Z]\+_NODE.*/\1/p' src/parse.c | sort | uniq); do
     # it can be documented in the following ways.
     # 1. "Properties for device type `blah:`
-    if egrep "## Properties for device type \`$term:\`" doc/netplan-yaml.md > /dev/null; then
+    if egrep "## Properties for device type \`$term:\`" doc/reference/netplan-yaml.md > /dev/null; then
         continue
     fi
 
     # 2. "[blah, ]**blah**[, **blah2**]: (scalar|bool|...)
-    if egrep "Alias: \*\*\`$term\`\*\*|\*\*\`$term\`\*\*.*\((scalar|boolean|mapping|sequence of scalars|sequence of mappings|sequence of sequence of scalars)" doc/netplan-yaml.md > /dev/null; then
+    if egrep "Alias: \*\*\`$term\`\*\*|\*\*\`$term\`\*\*.*\((scalar|boolean|mapping|sequence of scalars|sequence of mappings|sequence of sequence of scalars)" doc/reference/netplan-yaml.md > /dev/null; then
         continue
     fi