diff --git a/.gitignore b/.gitignore index 739bc992b..fb082f4e4 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ __pycache__ src/_features.h netplan_cli/_features.py dbus/io.netplan.Netplan.service +.DS_Store diff --git a/doc/.sphinx/spellingcheck.yaml b/doc/.sphinx/spellingcheck.yaml index d35477ab8..4d3da33e9 100644 --- a/doc/.sphinx/spellingcheck.yaml +++ b/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 diff --git a/doc/conf.py b/doc/conf.py index 2e06d63d6..82dccb07c 100644 --- a/doc/conf.py +++ b/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', } ############################################################ diff --git a/doc/generator.md b/doc/explanation/generator.md similarity index 100% rename from doc/generator.md rename to doc/explanation/generator.md diff --git a/doc/explanation.md b/doc/explanation/index.md similarity index 100% rename from doc/explanation.md rename to doc/explanation/index.md diff --git a/doc/nm-all.md b/doc/explanation/nm-all.md similarity index 100% rename from doc/nm-all.md rename to doc/explanation/nm-all.md diff --git a/doc/security.md b/doc/explanation/security.md similarity index 98% rename from doc/security.md rename to doc/explanation/security.md index e9d099be8..89c285b45 100644 --- a/doc/security.md +++ b/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 diff --git a/doc/structure-id.md b/doc/explanation/structure-id.md similarity index 100% rename from doc/structure-id.md rename to doc/explanation/structure-id.md diff --git a/doc/contribute-docs.md b/doc/howto/contribute-docs.md similarity index 100% rename from doc/contribute-docs.md rename to doc/howto/contribute-docs.md diff --git a/doc/creating-link-aggregation.md b/doc/howto/creating-link-aggregation.md similarity index 100% rename from doc/creating-link-aggregation.md rename to doc/howto/creating-link-aggregation.md diff --git a/doc/dbus-config.md b/doc/howto/dbus-config.md similarity index 100% rename from doc/dbus-config.md rename to doc/howto/dbus-config.md diff --git a/doc/examples.md b/doc/howto/examples.md similarity index 100% rename from doc/examples.md rename to doc/howto/examples.md diff --git a/doc/howto.md b/doc/howto/index.md similarity index 100% rename from doc/howto.md rename to doc/howto/index.md diff --git a/doc/matching-interface-by-mac-address.md b/doc/howto/matching-interface-by-mac-address.md similarity index 100% rename from doc/matching-interface-by-mac-address.md rename to doc/howto/matching-interface-by-mac-address.md diff --git a/doc/multi-nic-vm-host-with-bonds-and-vlans.md b/doc/howto/multi-nic-vm-host-with-bonds-and-vlans.md similarity index 93% rename from doc/multi-nic-vm-host-with-bonds-and-vlans.md rename to doc/howto/multi-nic-vm-host-with-bonds-and-vlans.md index 76a010ec1..2c1d9dfbf 100644 --- a/doc/multi-nic-vm-host-with-bonds-and-vlans.md +++ b/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 ``` \ No newline at end of file diff --git a/doc/netplan-everywhere.md b/doc/howto/netplan-everywhere.md similarity index 100% rename from doc/netplan-everywhere.md rename to doc/howto/netplan-everywhere.md diff --git a/doc/single-nic-vm-host-with-vlans.md b/doc/howto/single-nic-vm-host-with-vlans.md similarity index 89% rename from doc/single-nic-vm-host-with-vlans.md rename to doc/howto/single-nic-vm-host-with-vlans.md index b1e4dc643..765cdf239 100644 --- a/doc/single-nic-vm-host-with-vlans.md +++ b/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 ``` \ No newline at end of file diff --git a/doc/single-nic-vm-host.md b/doc/howto/single-nic-vm-host.md similarity index 89% rename from doc/single-nic-vm-host.md rename to doc/howto/single-nic-vm-host.md index aca0168f1..19fa08e4e 100644 --- a/doc/single-nic-vm-host.md +++ b/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 ``` diff --git a/doc/using-static-ip-addresses.md b/doc/howto/using-static-ip-addresses.md similarity index 100% rename from doc/using-static-ip-addresses.md rename to doc/howto/using-static-ip-addresses.md diff --git a/doc/index.md b/doc/index.md index d65763ad8..c6f90de00 100644 --- a/doc/index.md +++ b/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 diff --git a/doc/meson.build b/doc/meson.build index a4fc17150..4b1c4728a 100644 --- a/doc/meson.build +++ b/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, diff --git a/doc/apidoc/inc-netdef.md b/doc/reference/apidoc/inc-netdef.md similarity index 100% rename from doc/apidoc/inc-netdef.md rename to doc/reference/apidoc/inc-netdef.md diff --git a/doc/apidoc/inc-parse-nm.md b/doc/reference/apidoc/inc-parse-nm.md similarity index 100% rename from doc/apidoc/inc-parse-nm.md rename to doc/reference/apidoc/inc-parse-nm.md diff --git a/doc/apidoc/inc-parse.md b/doc/reference/apidoc/inc-parse.md similarity index 100% rename from doc/apidoc/inc-parse.md rename to doc/reference/apidoc/inc-parse.md diff --git a/doc/apidoc/inc-state.md b/doc/reference/apidoc/inc-state.md similarity index 100% rename from doc/apidoc/inc-state.md rename to doc/reference/apidoc/inc-state.md diff --git a/doc/apidoc/inc-types.md b/doc/reference/apidoc/inc-types.md similarity index 100% rename from doc/apidoc/inc-types.md rename to doc/reference/apidoc/inc-types.md diff --git a/doc/apidoc/inc-util.md b/doc/reference/apidoc/inc-util.md similarity index 100% rename from doc/apidoc/inc-util.md rename to doc/reference/apidoc/inc-util.md diff --git a/doc/apidoc/index.md b/doc/reference/apidoc/index.md similarity index 100% rename from doc/apidoc/index.md rename to doc/reference/apidoc/index.md diff --git a/doc/cli.md b/doc/reference/cli.md similarity index 100% rename from doc/cli.md rename to doc/reference/cli.md diff --git a/doc/reference.md b/doc/reference/index.md similarity index 100% rename from doc/reference.md rename to doc/reference/index.md diff --git a/doc/netplan-apply.md b/doc/reference/netplan-apply.md similarity index 100% rename from doc/netplan-apply.md rename to doc/reference/netplan-apply.md diff --git a/doc/netplan-dbus.md b/doc/reference/netplan-dbus.md similarity index 100% rename from doc/netplan-dbus.md rename to doc/reference/netplan-dbus.md diff --git a/doc/netplan-generate.md b/doc/reference/netplan-generate.md similarity index 100% rename from doc/netplan-generate.md rename to doc/reference/netplan-generate.md diff --git a/doc/netplan-get.md b/doc/reference/netplan-get.md similarity index 100% rename from doc/netplan-get.md rename to doc/reference/netplan-get.md diff --git a/doc/netplan-info.md b/doc/reference/netplan-info.md similarity index 100% rename from doc/netplan-info.md rename to doc/reference/netplan-info.md diff --git a/doc/netplan-ip.md b/doc/reference/netplan-ip.md similarity index 100% rename from doc/netplan-ip.md rename to doc/reference/netplan-ip.md diff --git a/doc/netplan-rebind.md b/doc/reference/netplan-rebind.md similarity index 100% rename from doc/netplan-rebind.md rename to doc/reference/netplan-rebind.md diff --git a/doc/netplan-set.md b/doc/reference/netplan-set.md similarity index 100% rename from doc/netplan-set.md rename to doc/reference/netplan-set.md diff --git a/doc/netplan-status.md b/doc/reference/netplan-status.md similarity index 100% rename from doc/netplan-status.md rename to doc/reference/netplan-status.md diff --git a/doc/netplan-try.md b/doc/reference/netplan-try.md similarity index 100% rename from doc/netplan-try.md rename to doc/reference/netplan-try.md diff --git a/doc/netplan-yaml.md b/doc/reference/netplan-yaml.md similarity index 99% rename from doc/netplan-yaml.md rename to doc/reference/netplan-yaml.md index 2857e7eab..9d4798f7b 100644 --- a/doc/netplan-yaml.md +++ b/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. - + \ No newline at end of file diff --git a/doc/tutorial.md b/doc/tutorial/index.md similarity index 100% rename from doc/tutorial.md rename to doc/tutorial/index.md diff --git a/doc/netplan-tutorial.md b/doc/tutorial/netplan-tutorial.md similarity index 100% rename from doc/netplan-tutorial.md rename to doc/tutorial/netplan-tutorial.md diff --git a/tests/validate_docs.sh b/tests/validate_docs.sh index 354dd5fe5..1fe478f69 100755 --- a/tests/validate_docs.sh +++ b/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