Improve how-to docs:

- Move intro to how-to landing page
- Make headings consistently use "How to"
- Remove (post-build) "How to" from TOC

.readthedocs.yaml

@@ -10,6 +10,10 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    post_build:
+      # Clipping 'How to' from Table of Contents
+      - sh doc/howtos.sh
 
 # Build documentation in the doc/ directory with Sphinx
 sphinx:

doc/contribute-docs.md

@@ -1,4 +1,4 @@
-# Contribute documentation
+# How to contribute documentation
 
 ## Reporting an issue
 

doc/dbus-config.md

@@ -1,59 +1,84 @@
-# Use D-Bus configuration API
+# How to use D-Bus configuration API
 
 See also:
 * [Netplan D-Bus reference](/netplan-dbus)
 * [`busctl` reference](https://www.freedesktop.org/software/systemd/man/busctl.html)
 
 Copy the current state from `/{etc,run,lib}/netplan/*.yaml` by creating a new configuration object:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan io.netplan.Netplan Config
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan io.netplan.Netplan Config
+
 o "/io/netplan/Netplan/config/ULJIU0"
 ```
 
 Read the merged YAML configuration:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Get
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 \
+io.netplan.Netplan.Config Get
+
 s "network:\n  ethernets:\n    eth0:\n      dhcp4: true\n  renderer: networkd\n  version: 2\n"
 ```
 
 Write a new configuration snippet into `70-snapd.yaml`:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Set ss "ethernets.eth0={dhcp4: false, dhcp6: true}" "70-snapd"
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 \
+io.netplan.Netplan.Config Set ss "ethernets.eth0={dhcp4: false, dhcp6: true}" "70-snapd"
+
 b true
 ```
 
 Check the newly written configuration:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Get
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 \
+io.netplan.Netplan.Config Get
+
 s "network:\n  ethernets:\n    eth0:\n      dhcp4: false\n      dhcp6: true\n  renderer: networkd\n  version: 2\n"
 ```
 
 Try to apply the current state of the configuration object:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Try u 20
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 \
+io.netplan.Netplan.Config Try u 20
+
 b true
 ```
 
 Accept the `Try()` state within the 20 seconds timeout, if not it will be auto-rejected:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Apply
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 \
+io.netplan.Netplan.Config Apply
+
 b true
 
 [SIGNAL] io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Changed() is triggered
 [OBJECT] io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 is removed from the bus
 ```
 
 Create a new configuration object and get the merged YAML configuration:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan io.netplan.Netplan Config
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan io.netplan.Netplan Config
+
 o "/io/netplan/Netplan/config/KC0IU0
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 io.netplan.Netplan.Config Get
+
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 \
+io.netplan.Netplan.Config Get
+
 s "network:\n  ethernets:\n    eth0:\n      dhcp4: false\n      dhcp6: true\n  renderer: networkd\n  version: 2\n"
 ```
 
 Reject that configuration object again:
-```
-$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 io.netplan.Netplan.Config Cancel
+
+```console
+busctl call io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 \
+io.netplan.Netplan.Config Cancel
+
 b true
 
 [SIGNAL] io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 io.netplan.Netplan.Config Changed() is triggered

doc/examples.md

@@ -1,22 +1,3 @@
-# Introduction
-
-Below is a collection of how-to guides for common scenarios.
-If you see a scenario missing or have one to contribute, please file a bug
-against this documentation with the example.
-
-To configure Netplan, save configuration files under `/etc/netplan/` with a
-`.yaml` extension (e.g. `/etc/netplan/config.yaml`), then run
-`sudo netplan apply`. This command parses and applies the configuration to the
-system. Configuration written to disk under `/etc/netplan/` will persist between
-reboots.
-
-For each of the example below, use the `renderer` that applies to your scenario.
-For example, for Ubuntu Desktop your `renderer` will probably be `NetworkManager`
-and `networkd` for Ubuntu Server.
-
-Also, see [/examples](https://github.com/canonical/netplan/tree/main/examples)
-on GitHub.
-
 # How to enable DHCP on an interface
 
 To let the interface named `enp3s0` get an address via DHCP, create a YAML file with the following:
@@ -533,25 +514,29 @@ network:
 
 # How to connect two systems with a WireGuard VPN
 
-Generate the private and public keys in the first peer:
+Generate the private and public keys in the first peer. Run the following commands with administrator privileges:
 
-```bash
-# wg genkey > private.key
-# wg pubkey < private.key > public.key
-# cat private.key
+```console
+wg genkey > private.key
+wg pubkey < private.key > public.key
+
+cat private.key
 UMjI9WbobURkCDh2RT8SRM5osFI7siiR/sPOuuTIDns=
-# cat public.key
+
+cat public.key
 EdNnZ1/2OJZ9HcScSVcwDVUsctCkKQ/xzjEyd3lZFFs=
 ```
 
 Do the same in the second peer:
 
-```bash
-# wg genkey > private.key
-# wg pubkey < private.key > public.key
-# cat private.key
+```console
+wg genkey > private.key
+wg pubkey < private.key > public.key
+
+cat private.key
 UAmjvLDVuV384OWFJkmI4bG8AIAZAfV7LarshnV3+lc=
-# cat public.key
+
+cat public.key
 AIm+QeCoC23zInKASmhu6z/3iaT0R2IKraB7WwYB5ms=
 ```
 

doc/howto.md

@@ -1,6 +1,27 @@
 # How-to guides
 
+Below is a collection of how-to guides for common scenarios.
+If you see a scenario missing or have one to contribute, please,
+[file a bug](https://bugs.launchpad.net/netplan/+filebug) against this
+documentation with the example.
+
+To configure Netplan, save configuration files in the `/etc/netplan/` directory
+with a `.yaml` extension (e.g. `/etc/netplan/config.yaml`), then run
+`sudo netplan apply`. This command parses and applies the configuration to the
+system. Configuration written to disk under `/etc/netplan/` persists between
+reboots.
+
+For each of the example below, use the `renderer` that applies to your scenario.
+For example, for Ubuntu Desktop the `renderer` is usually `NetworkManager`,
+and `networkd` for Ubuntu Server.
+
+Also, see [/examples](https://github.com/canonical/netplan/tree/main/examples)
+on GitHub.
+
 ```{toctree}
+:maxdepth: 1
+:name: cipisek
+
 examples
 dbus-config
 netplan-everywhere

doc/howtos.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+sed -i '/toctree-l2.*>How to / s/How to \(.\)/\U\1/' \
+   ../${READTHEDOCS_VERSION}/_readthedocs/html/*/*.html \
+   ../${READTHEDOCS_VERSION}/_readthedocs/html/*.html \

doc/netplan-everywhere.md

@@ -1,4 +1,4 @@
-# Desktop integration
+# How to integrate Netplan with desktop
 
 ## NetworkManager YAML settings back end