Add shared file with hyperlinks

Author: rgaiacs

source/concepts.rst

@@ -49,7 +49,7 @@ Create a pod by running
 
 Start the pod by running
 
-.. code::bash
+.. code:: bash
 
     podman pod start pod-name
 

source/conf.py

@@ -28,6 +28,8 @@
 exclude_patterns = []
 
 
+with open("hyperlink-targets.rst", encoding="utf-8") as _hyperlink_targets:
+    rst_epilog = _hyperlink_targets.read()
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

source/hyperlink-targets.rst

@@ -0,0 +1,7 @@
+.. _Docker Desktop: https://www.docker.com/products/docker-desktop/
+.. _Docker Engine: https://docs.docker.com/engine/
+.. _Podman Desktop: https://podman-desktop.io/
+.. _Podman machine: https://podman-desktop.io/docs/podman/creating-a-podman-machine
+.. _Podman: https://podman.io/
+.. _WSL: https://learn.microsoft.com/en-us/windows/wsl/
+.. _PowerShell: https://learn.microsoft.com/en-us/powershell/

source/index.rst

@@ -6,7 +6,13 @@
 Podman Desktop Tutorial
 =======================
 
-`Podman <https://podman.io/>`_ is an open source container management tool similar to `Docker Engine <https://docs.docker.com/engine/>`_. And `Podman Desktop <https://podman-desktop.io/>`_ is an open source client for Podman similar to `Docker Desktop <https://www.docker.com/products/docker-desktop/>`_.
+`Podman`_ is an open source container management tool similar to `Docker Engine`_. And `Podman Desktop`_ is open source client for Podman similar to `Docker Desktop`_.
+
+.. note::
+
+    If you have experience with Docker, you might want to jump to :doc:`full-example`.
+
+This tutorial will guide you on how to use Podman and Podman Desktop.
 
 ============================== =================================== ======================================
 Feature                        Podman                              Docker

source/install.rst

@@ -1,53 +1,57 @@
 Install
 =======
 
-Visit `Installing Podman Desktop <https://podman-desktop.io/docs/installation>`_ section from the `Podman Desktop documentation <https://podman-desktop.io/docs/>`_ for the steps to install Podman Desktop on Windows, macOS, and GNU/Linux.
+Visit `Installing Podman Desktop <https://podman-desktop.io/docs/installation>`_ section from the `Podman Desktop documentation <https://podman-desktop.io/docs/>`_ for the steps to install `Podman Desktop`_` on Windows, macOS, and GNU/Linux.
 
-On Windows and macOS, Podman Desktop will, by default, create a `Podman machine <https://podman-desktop.io/docs/podman/creating-a-podman-machine>`_ because Windows and macOS cannot run containers natively.
+On Windows and macOS, `Podman Desktop`_` will, by default, create a `Podman machine`_ because Windows and macOS cannot run containers natively.
 
-On Windows, you can use any `Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/>`_ to run Podman and have Podman Desktop managing Podman via SSH. The next section will provide more details for this.
+On Windows, you can use any Windows Subsystem for Linux (`WSL`_) to run Podman and have Podman Desktop managing Podman via SSH. The next section will provide more details for this.
 
 Configure Remote Access
 -----------------------
 
 1.  Enable remote connection on Podman Desktop's ``Settings``, ``Preferences``, ``Extension: Podman``.
-2.  Generate a SSH key.
+
+2.  Generate a SSH key on that you use, for example, the Windows machine.
 
     .. code:: bash
 
         ssh-keygen -t ed25519
 
-3.  Copy the public SSH key to the remote machine's ``~/.ssh/authorized_keys``.
-4.  On the GNU/Linux remote machine, enable Podman's socket.
+3.  On the GNU/Linux remote machine, install the SSH server.
+
+4.  On the GNU/Linux remote machine, start and enable the SSH server.
+
+5.  Copy the SSH key to ``~/.ssh/authorized_keys`` from the GNU/Linux remote machine.
+
+6.  Test the SSH connection from the Windows machien to the GNU/Linux remote machine.
+
+7.  On the GNU/Linux remote machine, enable Podman's socket.
 
     .. code:: bash
 
-        sudo systemctl enable podman.socket
-        sudo systemctl start podman.socket
+        systemctl enable --user podman.socket
+        systemctl start --user podman.socket
 
-5.  On the GNU/Linux remote machine, confirm that the Podman's socket is enabled.
+8.  On the GNU/Linux remote machine, confirm that the Podman's socket is enabled.
 
     .. code:: bash
 
         systemctl status --user podman.socket
 
-6.  Add the connection to the remote Podman.
+9.  Add the connection to the remote Podman.
 
-    On the Windows machine, use `PowerShell <https://learn.microsoft.com/en-us/powershell/>`_ to run
+    On the Windows machine, use `PowerShell`_ to run
 
     .. code:: powershell
 
         podman system connection `
         add $env:username `
-        --identity c:\Users\$env:username\.ssh\id_rsa `
+        --identity c:\Users\$env:username\.ssh\id_ed25519 `
         ssh://$env:username@localhost:22/run/user/1000/podman/podman.sock
 
-    as described in `Podman Remote clients for macOS and Windows <https://github.com/containers/podman/blob/main/docs/tutorials/mac_win_client.md>`_.
-
-7.  Optionally, set the remote Podman as the default.
-
-    On the Windows machine, use `PowerShell <https://learn.microsoft.com/en-us/powershell/>`_ to run
+10. Confirm that the connection to the remote Podman was created.
 
     .. code:: powershell
 
-        podman system connection default $env:username
+        podman system connection ls

source/k8s-port.rst

@@ -173,10 +173,16 @@ that is expected to return ::
 Windows Subsystem for Linux (WLS)
 ---------------------------------
 
-Windows 10
-^^^^^^^^^^
+.. important::
+
+    `Windows 10 reached the end of support <https://support.microsoft.com/en-us/windows/windows-10-support-ends-on-october-14-2025-2ca8b313-1946-43d3-b55c-2b95b107f281>`_ on 14 October 14 2025.
+
+.. important::
+
+    The new `Mirrored mode networking <https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking>`_ is available on Windows 11 22H2 and higher. Old versions uses a `NAT (Network Address Translation) <https://learn.microsoft.com/en-us/windows/wsl/networking#default-networking-mode-nat>`_ based architecture for networking.
 
-WSL uses a `NAT (Network Address Translation) <https://learn.microsoft.com/en-us/windows/wsl/networking#default-networking-mode-nat>`_ based architecture for networking. This allows the use of the `loopback <https://en.wikipedia.org/wiki/Loopback>`_ address from Windows to access the machine running Podman, for example
+
+WSL allows the use of the `loopback <https://en.wikipedia.org/wiki/Loopback>`_ address from Windows to access the machine running Podman, for example
 
 .. code:: powershell
 
@@ -221,10 +227,3 @@ And use the IP address
 .. code:: powershell
 
     curl.exe http://172.25.11.50:8080
-
-Windows 11
-^^^^^^^^^^
-
-.. important::
-
-    The new `Mirrored mode networking <https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking>`_ is available on Windows 11 22H2 and higher.

source/k8s-volume.rst

@@ -25,7 +25,7 @@ Example with HostPathVolumeSource
 
 .. WARNING::
 
-    Podman is not able to access files in a WSL2 machine, for example ``\\wsl.localhost\Ubuntu\home\user\file``. This feature was requested in Podman's GitHub project issue `17986 <https://github.com/containers/podman/issues/17986>`_ and `21813 <https://github.com/containers/podman/issues/21813>`_.
+    Podman is not able to access files in a `WSL`_ machine, for example ``\\wsl.localhost\Ubuntu\home\user\file``. This feature was requested in Podman's GitHub project issue `17986 <https://github.com/containers/podman/issues/17986>`_ and `21813 <https://github.com/containers/podman/issues/21813>`_.
 
 .. ATTENTION::
 
@@ -98,7 +98,7 @@ Example with HostPathVolumeSource
 
 .. WARNING::
 
-    Podman is not able to access files in a WSL2 machine, for example ``\\wsl.localhost\Ubuntu\home\user\file``. This feature was requested in Podman's GitHub project issue `17986 <https://github.com/containers/podman/issues/17986>`_ and `21813 <https://github.com/containers/podman/issues/21813>`_.
+    Podman is not able to access files in a `WSL`_ machine, for example ``\\wsl.localhost\Ubuntu\home\user\file``. This feature was requested in Podman's GitHub project issue `17986 <https://github.com/containers/podman/issues/17986>`_ and `21813 <https://github.com/containers/podman/issues/21813>`_.
 
 .. ATTENTION::