From d2f7efea1d02ab612b7db8191033f836f6d19fa2 Mon Sep 17 00:00:00 2001 From: geoffreynyaga Date: Mon, 30 Jun 2025 11:23:15 +0300 Subject: [PATCH] vale spellcheck --- docs/.custom_wordlist.txt | 200 +----------------- docs/.sphinx/.wordlist.txt | 2 +- docs/.sphinx/get_vale_conf.py | 19 +- docs/Makefile | 31 ++- .../run-a-docker-container-in-multipass.md | 2 +- .../troubleshoot/troubleshoot-networking.md | 24 +-- 6 files changed, 53 insertions(+), 225 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 22656b6ab1..79b9265828 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,221 +1,23 @@ -# Leave a blank line at the end of this file to support concatenation -anbox -AnyConnect -ApplicationFirewall -ARP -autostart -backend +# Leave a black line at the bottom backend's -backends -BBCcode boolean -bootpd -BPF -cal -cdimages -CIFS -Citrix -cjk -cloneN -CloudFlare -cloudflared -CommonMark -conf -config CPU -cpu CPUs -cpus -cryptographically -CSV -customisations -customized -Cygwin -de dev -DHCP -DNS -dnscrypt -dnsmasq -dvipng echoless -ESET ethernet -facto -Fi -filesystem -fonts -freefont -GiB -GID -github -GPG -GUI -gui -gyre -hacky -hardcoded -https Hyperkit -ICMP -ing -init -init's -IP -ip IPs -ips -IPv -iUDP -jellyfin Junos Kaspersky -KiB -Kudu -lang -latexmk -launchd -libexec -libvirt -lifecycle -liger -localhost -lsof -macOS -macOS's -MACs -mDNSResponder -mentorship -metallb -MiB -microk -Microk -Microk8s -Minikube -minikube misconfiguration -mr -mscho -multipass -Multipass -Multipass's -multipassd -netplan -Netplan -Netscaler -NetworkManager -NGINX -nginx -nic NIC NICs -nilgai -numpad -OpenConnect -OpenGL -OpenSSL -OpenVPN -otf overallocate passwordless -plantuml -plist Portainer -Portainer's -PowerShell -provisioner -provisioners -PsExec -PSTools -QCOW -QEMU -RDP -Remmina -repo -resolv -SHA -SMB -snapshotN -socketfilterfw -SonicWall -SourceForge -SSHFS -subnet -sudo Symantec -TCP teardown -tex -texlive -TLS -TOC -trumpetfish -Tunnelblick -ubuntu -Ubuntu -UDP -UEFI -UID -umount -unalias unmount -Unmounting unmounts -userspace -usr -UTF -utils -VcXsrv -VirtualBox -VirtualBox's -vm -VM -VM's -vmnet -VMs -VNC -VPN VPNs -WCAG -whipsnake -Wi -xetex -xindy -XLaunch -Xming -XOrg -XQuartz - -aaryan -andreitoterman -bagustris -bo -candlerb -dan -davidekete -georgeliaojia -gzanchi -henryschreineriii -itecompro -luisp -makin -naynayu -ng -nhart -nottrobin -pitifulpete -porwal -QuantumLibet -ricab -ros -roscigno -saviq -sergiusens -sharder -shuuji -sowasred -sparkiegeek -sven -tmihoc -townsend -undefynd diff --git a/docs/.sphinx/.wordlist.txt b/docs/.sphinx/.wordlist.txt index be5021a1f6..e9cc79a81c 100644 --- a/docs/.sphinx/.wordlist.txt +++ b/docs/.sphinx/.wordlist.txt @@ -61,4 +61,4 @@ UI UUID VM webhook -YAML +YAML \ No newline at end of file diff --git a/docs/.sphinx/get_vale_conf.py b/docs/.sphinx/get_vale_conf.py index 9ee2d0b5f6..ec1bf0f1ff 100644 --- a/docs/.sphinx/get_vale_conf.py +++ b/docs/.sphinx/get_vale_conf.py @@ -5,7 +5,6 @@ DIR = os.getcwd() - def main(): if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"): print("Vale directory exists") @@ -23,6 +22,22 @@ def main(): file.write(download.text) file.close() + # Update dictionary + if os.path.exists(f"{DIR}/.sphinx/styles/config/dictionaries"): + print("Dictionary directory exists") + else: + os.makedirs(f"{DIR}/.sphinx/styles/config/dictionaries") + url = ( + "https://api.github.com/repos/canonical/praecepta/" + + "contents/styles/config/dictionaries" + ) + r = requests.get(url) + for item in r.json(): + download = requests.get(item["download_url"]) + file = open(".sphinx/styles/config/dictionaries/" + item["name"], "w") + file.write(download.text) + file.close() + if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"): print("Vocab directory exists") else: @@ -50,4 +65,4 @@ def main(): if __name__ == "__main__": - main() + main() \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index ed04e3a3c9..8042799d5a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,6 +17,7 @@ ALLFILES = *.rst **/*.rst METRICSDIR = $(SOURCEDIR)/.sphinx/metrics REQPDFPACKS = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng CONFIRM_SUDO ?= N +VALE_CONFIG = $(SPHINXDIR)/vale.ini # Put it first so that "make" without argument is like "make help". help: @@ -61,6 +62,14 @@ $(VENVDIR): @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt @touch $(VENVDIR) +vale-install: install + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale + @. $(VENV); test -f $(VALE_CONFIG) || python3 $(SPHINXDIR)/get_vale_conf.py + @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINXDIR)/styles/woke.filter + @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/error.filter + @echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINXDIR)/styles/spelling.filter + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --version \; + woke-install: @type woke >/dev/null 2>&1 || \ { \ @@ -124,10 +133,17 @@ clean-doc: git clean -fx "$(BUILDDIR)" rm -rf $(SPHINXDIR)/.doctrees -spellcheck: spellcheck-install - . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) +vale-spelling: vale-install + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt + @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/spelling.filter' --glob='*.{md,rst}' $(TARGET) + @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt + + +spellcheck: vale-spelling -spelling: html spellcheck +spelling: clean-doc vale-spelling # clean built html and Use Vale for spelling check linkcheck: install . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; } @@ -140,16 +156,11 @@ woke: woke-install pa11y: pa11y-install html find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) -vale: install - @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale - @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py - @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; +vale: vale-install @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt @cat $(SPHINXDIR)/.wordlist.txt $(SOURCEDIR)/.custom_wordlist.txt >> $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt - @echo "" @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" - @echo "" - @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,rst}' $(TARGET) || true + @. $(VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINXDIR)/styles/error.filter' --glob='*.{md,rst}' $(TARGET) @cat $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt > $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept.txt && rm $(SPHINXDIR)/styles/config/vocabularies/Canonical/accept_backup.txt pdf-prep: install diff --git a/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md b/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md index 0552ce1992..66a159e498 100644 --- a/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md +++ b/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md @@ -199,4 +199,4 @@ You can now access your Ghost blog by going to the published port indicated in t There it is, your blog running within a Docker container inside Multipass! -For next steps, try out Portainer’s other App Templates (Step 5), or check out [Docker Hub](https://hub.docker.com/search?type=image) for more containers to try. If you want to try out container orchestration, [Microk8s](https://microk8s.io/) or Multipass’ [Minikube](https://minikube.sigs.k8s.io/docs/) blueprint are great places to start. +For next steps, try out Portainer’s other App Templates (Step 5), or check out [Docker Hub](https://hub.docker.com/search?type=image) for more containers to try. If you want to try out container orchestration, [Microk8s](https://microk8s.io/) or Multipass’ [`Minikube`](https://minikube.sigs.k8s.io/docs/) blueprint are great places to start. diff --git a/docs/how-to-guides/troubleshoot/troubleshoot-networking.md b/docs/how-to-guides/troubleshoot/troubleshoot-networking.md index 1270aa644d..e87843072e 100644 --- a/docs/how-to-guides/troubleshoot/troubleshoot-networking.md +++ b/docs/how-to-guides/troubleshoot/troubleshoot-networking.md @@ -17,7 +17,7 @@ On macOS, the QEMU driver employs the Hypervisor.framework. This framework manag On creation of an instance, the Hypervisor framework on the host uses macOS's **Internet Sharing** mechanism to: 1. Create a virtual switch and connect each instance to it (subnet 192.168.64.*). -2. Provide DHCP and DNS resolution on this switch at 192.168.64.1 (via bootpd & mDNSResponder services running on the host). This is configured by an auto-generated file (`/etc/bootpd.plist`), but editing this is pointless as macOS regenerates it as it desires. +2. Provide DHCP and DNS resolution on this switch at 192.168.64.1 (via `bootpd` & `mDNSResponder` services running on the host). This is configured by an auto-generated file (`/etc/bootpd.plist`), but editing this is pointless as macOS regenerates it as it desires. Note that, according to **System Preferences > Sharing**, the **Internet Sharing** service can appear disabled. This is fine---in the background, it will still be enabled to support instances. @@ -25,14 +25,14 @@ Note that, according to **System Preferences > Sharing**, the **Internet Sharing * VPN software can be aggressive at managing routes and may route 192.168.64 subnet through the VPN interface, instead of keeping it locally available. * Possible culprits: OpenVPN, F5, Dell SonicWall, Cisco AnyConnect, Citrix/Netscaler Gateway, Jupiter Junos Pulse / Pulse Secure. - * Tunnelblick doesn’t cause problems. + * `Tunnelblick` doesn’t cause problems. * Cisco Umbrella Roaming Client it binds to localhost:53 which clashes with Internet Sharing, breaking the instance’s DNS. * dnscrypt-proxy/dnscrypt-wrapper/cloudflared-proxy \ The default configuration binds to localhost port 53, clashing with Internet Sharing. * Another `dnsmasq` process bound to localhost port 53 -* Custom DHCP server bound to port 67? ("sudo lsof -iUDP:67 -n -P" should show launchd & bootpd only) +* Custom DHCP server bound to port 67? (`sudo lsof -iUDP:67 -n -P` should show `launchd` & `bootpd` only) * macOS updates can make changes to the firewall and leave instances in unknown state; see {ref}`troubleshoot-networking-issues-caused-by-macos-update` below. ### Problem class @@ -59,9 +59,9 @@ The default configuration binds to localhost port 53, clashing with Internet Sha 1. Is Firewall enabled? 1. If so it must not "Block all incoming connections" * Blocking all incoming connections prevents a DHCP server from running locally, to give an IP to the instance. - * It’s OK to block incoming connections to "multipassd" however. + * It’s OK to block incoming connections to `"multipassd"` however. 1. VPN -1. Little Snitch - defaults are good, it should permit mDNSResponder and bootpd access to BPF +1. Little Snitch - defaults are good, it should permit `mDNSResponder` and `bootpd` access to BPF If you're having trouble downloading images and/or see `Unknown error`s when trying to `multipass launch -vvv`, Little Snitch may be interfering with `multipassd`'s network access (ref. [#1169](https://github.com/canonical/multipass/issues/1169)) 1. Internet Sharing - doesn’t usually clash @@ -85,7 +85,7 @@ Maybe `-static` route helps? If using Cisco AnyConnect, try using OpenConnect (`brew install openconnect`) instead as it messes with routes less (but your company sysadmin/policy may not permit/authorise this). -* It monitors the routing table so may prevent any customisation. Here is [a very hacky workaround](https://unix.stackexchange.com/questions/106304/route-add-no-longer-works-when-i-connected-to-vpn-via-cisco-anyconnect-client/501094#501094). +* It monitors the routing table so may prevent any customisation. Here is [a very handy but non-standard workaround](https://unix.stackexchange.com/questions/106304/route-add-no-longer-works-when-i-connected-to-vpn-via-cisco-anyconnect-client/501094#501094). Does your VPN software provide a "split connection" option, where VPN sysadmin can designate a range of IP addresses to **not** be routed through the VPN? * Cisco does @@ -109,11 +109,11 @@ sudo pfctl -f /etc/pf.conf #### Configure Multipass to use a different subnet -Edit `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist` to change the "Shared_Net_Address" value to something other than `192.168.64.1 -`. -* it works if you edit the plist file and stay inside 192.168 range, as Multipass hardcoded for this +Edit `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist` to change the `"Shared_Net_Address"` value to something other than `192.168.64.1 -`. +* it works if you edit the `plist` file and stay inside 192.168 range, as Multipass hard-coded for this ```{note} -If you change the subnet and launch an instance, it will get an IP from that new subnet. But if you try changing it back, the change is reverted on next instance start. It appears that the DHCP server reads the last IP in `/var/db/dhcpd_leases`, decides the subnet from that, and updates Shared_Net_Address to match. So, the only way to really revert this change is to edit or delete `/var/db/dhcpd_leases`. +If you change the subnet and launch an instance, it will get an IP from that new subnet. But if you try changing it back, the change is reverted on next instance start. It appears that the DHCP server reads the last IP in `/var/db/dhcpd_leases`, decides the subnet from that, and updates `Shared_Net_Address` to match. So, the only way to really revert this change is to edit or delete `/var/db/dhcpd_leases`. ``` (troubleshoot-networking-dns-problems)= @@ -233,9 +233,9 @@ google.ie. 39 IN A 74.125.193.94 This implies the problem is with the macOS **Internet Sharing** feature---for some reason, its built-in DNS server is broken. -The built-in DNS server should be "mDNSResponder", which binds to localhost on port 53. +The built-in DNS server should be `"mDNSResponder"`, which binds to localhost on port 53. -If using Little Snitch or another per-process firewall, ensure mDNSResponder can establish outgoing connections. The macOS’s built-in firewall should not interfere with it. +If using Little Snitch or another per-process firewall, ensure `mDNSResponder` can establish outgoing connections. The macOS’s built-in firewall should not interfere with it. Check what is bound to that port on the host with: @@ -281,7 +281,7 @@ This means that applications that rely on additional IP addresses, such as [meta When upgrading macOS to 12.4 (this might happen however also when upgrading to other versions), macOS makes changes to the firewall. If the instances are not stopped before the update, it is possible the connection to the instances are blocked by the macOS firewall. We cannot know what is exactly the change introduced to the firewall, it seems the Apple's `bootpd` stops replying DHCP requests. -There are some procedures that can help to overcome this issue (see [issue #2387](https://github.com/canonical/multipass/issues/2387) on the Multipass GitHub repo for a discussion on this and some alternative solutions). First, you can try to: +There are some procedures that can help to overcome this issue (see [issue #2387](https://github.com/canonical/multipass/issues/2387) on the Multipass GitHub repository for a discussion on this and some alternative solutions). First, you can try to: * Reboot the computer. * Disable and then re-enable Internet sharing and/or the firewall.