diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6ce4ecb55..d49c3d4cb 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/doc/Makefile b/doc/Makefile index a76d8aab9..7be7697f3 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -58,6 +58,8 @@ run: install # Doesn't depend on $(BUILDDIR) to rebuild properly at every run. html: install . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS) + @echo "\nClipping 'How to' from Table of Contents:" + sed -i '/toctree-l2.*>How to / s/How to \(.\)/\U\1/' _build/**/*.html epub: install . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS) diff --git a/doc/contribute-docs.md b/doc/contribute-docs.md index 66c55ad06..00cb111e2 100644 --- a/doc/contribute-docs.md +++ b/doc/contribute-docs.md @@ -1,4 +1,4 @@ -# Contribute documentation +# How to contribute documentation ## Reporting an issue diff --git a/doc/dbus-config.md b/doc/dbus-config.md index 4ea8040f4..1b14f35e6 100644 --- a/doc/dbus-config.md +++ b/doc/dbus-config.md @@ -1,42 +1,59 @@ -# 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 @@ -44,16 +61,24 @@ b true ``` 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 diff --git a/doc/examples.md b/doc/examples.md index 58ada43bc..c6c417858 100644 --- a/doc/examples.md +++ b/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= ``` diff --git a/doc/howto.md b/doc/howto.md index dd8d00dd9..e42c85314 100644 --- a/doc/howto.md +++ b/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 diff --git a/doc/howtos.sh b/doc/howtos.sh new file mode 100755 index 000000000..ab4574edf --- /dev/null +++ b/doc/howtos.sh @@ -0,0 +1,3 @@ +#!/bin/sh +sed -i '/toctree-l2.*>How to / s/How to \(.\)/\U\1/' \ + ../../../artifacts/${READTHEDOCS_VERSION}/sphinx/_build/**/*.html diff --git a/doc/netplan-everywhere.md b/doc/netplan-everywhere.md index e95fcb6b9..8d2c353f0 100644 --- a/doc/netplan-everywhere.md +++ b/doc/netplan-everywhere.md @@ -1,4 +1,4 @@ -# Desktop integration +# How to integrate Netplan with desktop ## NetworkManager YAML settings back end