Improve how-to docs:

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

doc/conf.py

@@ -1,6 +1,9 @@
 import sys
-
 import datetime
+import atexit
+import fileinput
+import os
+import re
 
 # Custom configuration for the Sphinx documentation builder.
 # All configuration specific to your project should be done in this file.
@@ -373,3 +376,31 @@
 if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
     html_js_files.append('github_issue_links.js')
 html_js_files.extend(custom_html_js_files)
+
+
+# Clip the "How to" string from how-to titles in the left navigation sidebar
+#     and capitalizes the first letter of the remaining title.
+def clip_howto():
+    pattern = re.compile(r'(toctree-l2.*>)How to ([a-zA-Z])')
+    # Check if the build is running on ReadTheDocs
+    if os.environ.get('READTHEDOCS') == 'True':
+        output_dir = os.environ.get('READTHEDOCS_OUTPUT') + '/html'
+    else:
+        output_dir = '_build'
+
+    print("Clipping 'How to' from the Table of Contents...")
+
+    for root, dirs, files in os.walk(output_dir):
+        for file in files:
+            if file.endswith('.html'):
+                file_path = os.path.join(root, file)
+
+                with fileinput.FileInput(file_path, inplace=True) as f:
+                    for line in f:
+                        line = pattern.sub(lambda match: match.group(1) + match.group(2).upper(), line)
+                        print(line, end='')
+
+
+# Register the clip_howto function to be called on exit
+atexit.register(clip_howto)
+# End how-to clipping

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,26 @@
 # 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
+
 examples
 dbus-config
 netplan-everywhere

doc/netplan-everywhere.md

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