Merge pull request #3940 from canonical/small-fixes-to-docs-structure

Small fixes to docs structure

docs/conf.py

@@ -133,10 +133,6 @@
     # NOTE: If set, links for viewing the documentation source files
     #       and creating GitHub issues are added at the bottom of each page.
     "github_url": "https://github.com/canonical/multipass",
-    # NOTE TO GIULIA: This line was suggested by Shane to enable the feedback button,
-    # but it doesn't work at the moment.
-    # 'github_issues': 'enabled',
-
     # Docs branch in the repo; used in links for viewing the source files
     #
     # TODO: To customise the branch, uncomment and update as needed.
@@ -150,6 +146,8 @@
     # "sequential_nav": "both",
     # TODO: To enable listing contributors on individual pages, set to True
     "display_contributors": False,
+    # The following line enables the "Give feedback" button.
+    "github_issues": "enabled",
 }
 
 # Project slug; see https://meta.discourse.org/t/what-is-category-slug/87897
@@ -269,6 +267,7 @@
 .. include:: /reuse/links.txt
 """
 
+
 # Feedback button at the top; enabled by default
 #
 # TODO: To disable the button, uncomment this.

docs/explanation/authentication.md

@@ -5,21 +5,21 @@
 
 Before executing any commands, Multipass requires clients to authenticate with the service. Multipass employs an authentication process based on x509 certificates signed by elliptic curve (EC) keys, powered by OpenSSL, to authenticate clients. When a client connects, Multipass verifies the client's certificate, ensuring only authenticated clients can communicate with the service.
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 Linux and macOS hosts currently use a Unix domain socket for client and daemon communication. Upon first use, this socket only allows a client to connect via a user belonging to the group that owns the socket. For example, this group could be `sudo`, `admin`, or `wheel` and the user needs to belong to this group or else permission will be denied when connecting.
 
 After the first client connects with a user belonging to the socket's admin group, the client's OpenSSL certificate will be accepted by the daemon and the socket will be then be open for all users to connect. Any other user trying to connect to the Multipass service will need to authenticate with the service using the previously set [`local.passphrase`](/reference/settings/local-passphrase).
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 Linux and macOS hosts currently use a Unix domain socket for client and daemon communication. Upon first use, this socket only allows a client to connect via a user belonging to the group that owns the socket. For example, this group could be `sudo`, `admin`, or `wheel` and the user needs to belong to this group or else permission will be denied when connecting.
 
 After the first client connects with a user belonging to the socket's admin group, the client's OpenSSL certificate will be accepted by the daemon and the socket will be then be open for all users to connect. Any other user trying to connect to the Multipass service will need to authenticate with the service using the previously set [`local.passphrase`](/reference/settings/local-passphrase).
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 The Windows host uses a TCP socket listening on port 50051 for client connections. This socket is open for all to use since there is no concept of file ownership for TCP sockets. This is not very secure in that any Multipass client can connect to the service and issue any commands.
 
 To close this gap, the client will now need to be authenticated with the Multipass service. To ease the burden of having to authenticate the client, the user who installs the updated version of Multipass will automatically have their clients authenticated with the service. Any other users connecting to the service will have to use authenticate using the previously set [`local.passphrase`](/reference/settings/local-passphrase).

docs/explanation/mount.md

@@ -30,19 +30,19 @@ Native mounts use driver-dependent technologies to achieve the high performance.
 (security-considerations-mount)=
 ## Security considerations
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 Because mounts are performed as `root` -- unless installed via snap, see below -- they allow write access to the whole host operating system. But since only privileged users (members of `sudo`, `wheel`, `admin` groups) can use Multipass, this isn't a concern on Linux.
 
 If Multipass is installed via snap package, [snap confinement](https://snapcraft.io/docs/snap-confinement) prevents mounts outside of the `/home` directory (and to hidden files/folders in the `/home` directory) and possibly, removable media (depending on the connected interfaces). Still, a user (A) with access to Multipass could access mounts that a different user (B) established to B's home directory (that is, outside of A's home).
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 Because mounts are performed as `root`, they allow write access to the whole host operating system. But since only privileged users (members of `sudo`, `wheel`, `admin` groups) can use Multipass, this isn't a concern on macOS.
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 Because mounts are performed as privileged users (`SYSTEM` on Windows), they allow write access to the whole host operating system.
 
 For historical reasons, mounts are disabled by default on Windows, even though in the current version of Multipass users need to authenticate with the daemon before it will service their requests. See [`local.privileged-mounts`](/reference/settings/local-privileged-mounts) for information on how to enable them if needed.

docs/how-to-guides/customise-multipass/configure-multipasss-default-logging-level.md → docs/how-to-guides/customise-multipass/configure-multipass-default-logging-level.md

@@ -1,4 +1,4 @@
-(how-to-guides-customise-multipass-configure-multipasss-default-logging-level)=
+(how-to-guides-customise-multipass-configure-multipass-default-logging-level)=
 # Configure Multipass’s default logging level
 
 > See also: [Logging levels](/reference/logging-levels)
@@ -7,9 +7,9 @@ This document demonstrates how to configure the default logging level of the Mul
 
 ## Changing the default logging level
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 
 First, stop the Multipass daemon:
 
@@ -37,7 +37,7 @@ sudo snap start multipass
 
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 
 First, become `root`:
 
@@ -61,7 +61,7 @@ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist
 
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 
 First, open an administrator privileged PowerShell prompt.
 

docs/how-to-guides/customise-multipass/configure-where-multipass-stores-external-data.md

@@ -12,9 +12,9 @@ This document demonstrates how to configure the location where Multipass stores
 - When uninstalling Multipass, the uninstaller will not remove data stored in custom locations, so you'll have to deleted it manually.
 ```
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 
 First, stop the Multipass daemon:
 
@@ -86,7 +86,7 @@ sudo rm -rf /var/snap/multipass/common/cache/multipassd
 
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 
 First, become `root`:
 
@@ -124,7 +124,7 @@ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist
 
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 
 First, open a PowerShell prompt with administration privileges.
 
@@ -169,9 +169,9 @@ Remove-Item -Path "C:\ProgramData\Multipass\*" -Recurse
 
 ## Reverting back to the default location
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 
 Stop the Multipass daemon:
 
@@ -214,7 +214,7 @@ sudo rm -rf <path>
 
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 
 First, become `root`:
 
@@ -248,7 +248,7 @@ launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist
 
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 
 First, open a PowerShell prompt with administrator privileges.
 

docs/how-to-guides/customise-multipass/index.md

@@ -1,5 +1,5 @@
 (how-to-guides-customise-multipass-index)=
-# Customise-Multipass
+# Customise Multipass
 
 The following guides provide step-by-step instructions on how to customise Multipass to address specific needs, from managing Multipass drivers to configuring a graphical user interface.
 
@@ -11,7 +11,7 @@ The following guides provide step-by-step instructions on how to customise Multi
 - [Use a different terminal from the system icon](use-a-different-terminal-from-the-system-icon)
 - [Integrate with Windows Terminal](integrate-with-windows-terminal)
 - [Configure where Multipass stores external data](configure-where-multipass-stores-external-data)
-- [Configure Multipass’s default logging level](configure-multipasss-default-logging-level)
+- [Configure Multipass’s default logging level](configure-multipass-default-logging-level)
 
 <!-- REMOVED FROM DOCS AND MOVED TO COMMUNITY KNOWLEDGE
 - [Use Multipass remotely](/)
@@ -28,4 +28,12 @@ The following guides provide step-by-step instructions on how to customise Multi
 :maxdepth: 2
 :glob:
 
-*
+set-up-the-driver
+migrate-from-hyperkit-to-qemu-on-macos
+authenticate-clients-with-the-multipass-service
+build-multipass-images-with-packer
+set-up-a-graphical-interface
+use-a-different-terminal-from-the-system-icon
+integrate-with-windows-terminal
+configure-where-multipass-stores-external-data
+configure-multipass-default-logging-level

docs/how-to-guides/customise-multipass/set-up-a-graphical-interface.md

@@ -80,9 +80,9 @@ In this example, we will use the IP address `10.49.93.209` to connect to the RDP
 If the IP address of the instance is not displayed in the output of `multipass list`, you can obtain it directly from the instance, with the command `ip addr`.
 ```
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 
 On Linux, there are applications such as Remmina to visualise the desktop (make sure the package `remmina-plugin-rdp` is installed in your host along with `remmina`).
 
@@ -98,13 +98,13 @@ The system will ask for a username (`ubuntu`) and the password set above, and th
 
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 
 To connect on macOS, we can use the “Microsoft Remote Desktop” application, from the Mac App Store.
 
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 
 On Windows, we can connect to the RDP server with the “Remote Desktop Connection” application. There, we enter the virtual machine’s IP address, set the session to XOrg and enter the username and password we created on the previous step.
 
@@ -118,9 +118,9 @@ And we are done... a graphical desktop!
 
 It might be the case that we only want Multipass to launch one application and to see only that window, without having the need for a complete desktop. It turns out that this setup is simpler than the RDP approach, because we do not need the Multipass instance to deploy a full desktop. Instead, we can use X11 to connect the applications in the instance with the graphical capabilities of the host.
 
-`````{tab-set}
+`````{tabs}
 
-````{tab-item} Linux
+````{group-tab} Linux
 
 Linux runs X by default, so no extra software in the host is needed.
 
@@ -155,7 +155,7 @@ A small window containing the X logo will show up. Done!
 
 ````
 
-````{tab-item} macOS
+````{group-tab} macOS
 
 The first step in Mac is to make sure a X server is running. The easiest way is to install [XQuartz](https://www.xquartz.org).
 
@@ -167,7 +167,7 @@ Note to Apple Silicon users: some applications requiring OpenGL will not work th
 
 ````
 
-````{tab-item} Windows
+````{group-tab} Windows
 
 Windows knows nothing about X, therefore we need to install an X server. Here we will use [VcXsrv](https://sourceforge.net/projects/vcxsrv/). Other options would be [Xming](http://www.straightrunning.com/XmingNotes/) (the newest versions are paid, but older versions can still be downloaded for free from their [SourceForge site](https://sourceforge.net/projects/xming/)) or installing an X server in [Cygwin](https://cygwin.com/).