Workshop: fix broken Sphinx cross-references.

Many of the workshop pages links are directing to URLs that end with ".rst" instead of ".html", as a result, these links are broken. This commit introduces explicit targets and references to ensure that the pages are correctly linked. Signed-off-by: Francisco Trivino <ftrivino@redhat.com> Reviewed-By: Alexander Bokovoy <abokovoy@redhat.com> Reviewed-By: Florence Blanc-Renaud <flo@redhat.com>
freeipa · Sep 26, 2023 · 4af05dd · 4af05dd
1 parent 496e3ac
commit 4af05dd
Show file tree

Hide file tree

Showing 15 changed files with 74 additions and 47 deletions.
diff --git a/doc/workshop/1-server-install.rst b/doc/workshop/1-server-install.rst
@@ -1,4 +1,5 @@
-..
+.. _1-server-install:
+
   Copyright 2015-2018  Red Hat, Inc.
 
   This work is licensed under the Creative Commons Attribution 4.0
@@ -157,8 +158,8 @@ more!
 
 To prepare for the next unit, exit the ``server`` SSH session (but
 do not shut the VM down).  The next essential unit is
-`Unit 2: Enrolling client machines <2-client-install.rst>`_.
+:ref:`Unit 2: Enrolling client machines <2-client-install>`.
 
 Alternatively, if you would like to immediately install a replica
 server (essential for production deployments), you can take a detour
-to `Unit 7: Replica installation <7-replica-install.rst>`_.
+to :ref:`Unit 7: Replica installation <7-replica-install>`.
diff --git a/doc/workshop/10-ssh-key-management.rst b/doc/workshop/10-ssh-key-management.rst
@@ -1,9 +1,11 @@
+.. _10-ssh-key-management:
+
 Unit 10: SSH user and host key management
 =========================================
 
 **Prerequisites:**
 
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
 
 In this module you will explore how to use FreeIPA as a backend
 provider for SSH keys.  Instead of distributing ``authorized_keys``

diff --git a/doc/workshop/11-kerberos-ticket-policy.rst b/doc/workshop/11-kerberos-ticket-policy.rst
@@ -1,9 +1,11 @@
+.. _11-kerberos-ticket-policy:
+
 Unit 11: Kerberos ticket policy
 =========================================
 
 **Prerequisites:**
 
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
 
 In this module you will explore how to manage properties of Kerberos
 authentication and authorization in FreeIPA.

diff --git a/doc/workshop/12-external-idp-support.rst b/doc/workshop/12-external-idp-support.rst
@@ -1,9 +1,11 @@
+.. _12-external-idp-support:
+
 Unit 12: Authentication against external Identity Providers
 ===========================================================
 
 **Prerequisites:**
 
-- `Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy.rst>`_
+- :ref:`Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy>`
 
 In this module you will explore how to manage use external OAuth 2.0 servers to
 authorize issuance of Kerberos tickets in FreeIPA.

diff --git a/doc/workshop/2-client-install.rst b/doc/workshop/2-client-install.rst
@@ -1,9 +1,11 @@
+.. _2-client-install:
+
 Unit 2: Enrolling client machines
 ===================================
 
 **Prerequisites**:
 
-- `Unit 1: Installing the FreeIPA server <1-server-install.rst>`_
+- :ref:`Unit 1: Installing the FreeIPA server <1-server-install>`
 
 In this unit, you will enrol a *host* as a client of your FreeIPA
 domain.  This means that *users* in your FreeIPA realm (or Active
@@ -57,4 +59,4 @@ logged onto the host can also acquire Kerberos tickets for accessing
 *services* in your domain.
 
 You can now move on to
-`Unit 3: User management and Kerberos authentication <3-user-management.rst>`_.
+:ref:`Unit 3: User management and Kerberos authentication <3-user-management>`.
diff --git a/doc/workshop/3-user-management.rst b/doc/workshop/3-user-management.rst
@@ -1,3 +1,5 @@
+.. _3-user-management:
+
 Unit 3: User management and Kerberos authentication
 =====================================================
 
@@ -124,8 +126,8 @@ is a true *single sign-on* protocol!
 
 Now that you have created some users, it's time to define some
 access policies.  Proceed to
-`Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_.
+:ref:`Unit 4: Host-based access control (HBAC) <4-hbac>`.
 
 Alternatively, if you are interested in SSH public key management
 for users and hosts, jump ahead to
-`Unit 10: SSH user and host key management <10-ssh-key-management.rst>`_.
+:ref:`Unit 10: SSH user and host key management <10-ssh-key-management>`.
diff --git a/doc/workshop/4-hbac.rst b/doc/workshop/4-hbac.rst
@@ -1,9 +1,11 @@
+.. _4-hbac:
+
 Unit 4: Host-based access control (HBAC)
 ==========================================
 
 **Prerequisites:**
 
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
 
 FreeIPA's *host-based access control* (HBAC) feature allows you to
 define policies that restrict access to hosts or services based on
@@ -142,7 +144,7 @@ Now try ``alice``::
 This was the final mandatory unit in the workshop.  From here, there
 are several optional units you can choose from.  You can proceed
 directly to
-`Unit 5: Web application authentication and authorisation <5-web-app-authnz.rst>`_.
+:ref:`Unit 5: Web application authentication and authorisation <5-web-app-authnz>`.
 Otherwise,
-`return to the curriculum overview <workshop.rst#curriculum-overview>`_
+:ref:`return to the curriculum overview <curriculum-overview>`
 to see all the options.
diff --git a/doc/workshop/5-web-app-authnz.rst b/doc/workshop/5-web-app-authnz.rst
@@ -1,10 +1,12 @@
+.. _5-web-app-authnz:
+
 Unit 5: Web application authentication and authorisation
 ==========================================================
 
 **Prerequisites**:
 
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
-- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
+- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>`
 
 You can configure many kinds of applications to rely on FreeIPA's
 centralised authentication, including web applications.  In this
@@ -309,4 +311,4 @@ authenticated as ``bob`` instead?
 This unit is now concluded.  Now that you have mastered web app
 authentication, you'll want to configure TLS for your site.  Proceed
 to
-`Unit 6: Service certificates <6-cert-management.rst>`_.
+:ref:`Unit 6: Service certificates <6-cert-management>`.
diff --git a/doc/workshop/6-cert-management.rst b/doc/workshop/6-cert-management.rst
@@ -1,3 +1,5 @@
+.. _6-cert-management:
+
 Unit 6: Service certificates
 ================================
 
@@ -126,9 +128,9 @@ Restart Apache and make a request to the app over HTTPS::
 
 
 You can now proceed to
-`Unit 7: Replica installation <7-replica-install.rst>`_
+:ref:`Unit 7: Replica installation <7-replica-install>`
 or
-`Unit 8: Sudo rule management <8-sudorule.rst>`_.
+:ref:`Unit 8: Sudo rule management <8-sudorule>`.
 Otherwise,
-`return to the curriculum overview <workshop.rst#curriculum-overview>`_
+:ref:`return to the curriculum overview <curriculum-overview>`
 to see all the options.
diff --git a/doc/workshop/7-replica-install.rst b/doc/workshop/7-replica-install.rst
@@ -1,9 +1,11 @@
+.. _7-replica-install:
+
 Unit 7: Replica installation
 ==============================
 
 **Prerequisites**:
 
-- `Unit 1: Installing the FreeIPA server <1-server-install.rst>`_
+- :ref:`Unit 1: Installing the FreeIPA server <1-server-install>`
 
 FreeIPA is designed to be run in a replicated multi-master
 environment.  In this unit, we will install a replica of the
@@ -19,7 +21,7 @@ Client installation
 
 The first step of replica creation is to enrol the machine that will
 become the replica.  SSH to the ``replica`` VM and enrol it per
-`Unit 2: Enrolling client machines <2-client-install.rst>`_
+:ref:`Unit 2: Enrolling client machines <2-client-install>`
 
 Replica promotion
 -----------------
@@ -56,7 +58,7 @@ After ``ipa-replica-install`` finishes, the replica is operational.
 LDAP changes on any server will be replicated to all other servers.
 
 You can proceed to
-`Unit 8: Sudo rule management <8-sudorule.rst>`_
+:ref:`Unit 8: Sudo rule management <8-sudorule>`
 or
-`return to the curriculum overview <workshop.rst#curriculum-overview>`_
+:ref:`return to the curriculum overview <curriculum-overview>`
 to see all the available topics.
diff --git a/doc/workshop/8-sudorule.rst b/doc/workshop/8-sudorule.rst
@@ -1,10 +1,12 @@
+.. _8-sudorule:
+
 Unit 8: Sudo rule management
 ============================
 
 **Prerequisites**:
 
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
-- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
+- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>`
 
 Sudo is a program that allows users to run programs as another user
 with different privileges (possibly ``root``).  Sudo rules provide
@@ -241,4 +243,4 @@ restart (or start) Apache, but not run other commands via ``sudo``::
 
 
 This concludes the unit.  Now that you have Sudo rules working,
-proceed to `Unit 9: SELinux User Maps <9-selinux-user-map.rst>`_.
+proceed to :ref:`Unit 9: SELinux User Maps <9-selinux-user-map>`.
diff --git a/doc/workshop/9-selinux-user-map.rst b/doc/workshop/9-selinux-user-map.rst
@@ -1,11 +1,13 @@
+.. _9-selinux-user-map:
+
 Unit 9: SELinux User Maps
 =========================
 
 **Prerequisites**:
 
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
-- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_
-- `Unit 8: Sudo rule management <8-sudorule.rst>`_
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
+- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>`
+- :ref:`Unit 8: Sudo rule management <8-sudorule>`
 
 SELinux is a *mandatory access controls* mechanism for Linux,
 providing more powerful and flexible access control than traditional
@@ -43,7 +45,7 @@ will automatically be used.
 
 Recall that members of the ``sysadmin`` User Group already have
 access to ``webservers`` via the ``sysadmin_webservers`` rule that
-was created in `Unit 4: Host-based access control (HBAC)`_.  Create
+was created in :ref:`Unit 4: Host-based access control (HBAC)<4-hbac>`.  Create
 the SELinux User Map::
 
   [client]$ ipa selinuxusermap-add sysadmin_staff_t \
@@ -135,7 +137,7 @@ the program being run::
   Hello, world!
 
 This concludes the unit.  You can now proceed to
-`Unit 10: SSH user and host key management <10-ssh-key-management.rst>`_
+:ref:`Unit 10: SSH user and host key management <10-ssh-key-management>`
 or
-`return to the curriculum overview <workshop.rst#curriculum-overview>`_
+:ref:`return to the curriculum overview <curriculum-overview>`
 to see all the available topics.
diff --git a/doc/workshop/building.rst b/doc/workshop/building.rst
@@ -1,3 +1,5 @@
+.. _building:
+
 Building Vagrant box images
 ===========================
 

diff --git a/doc/workshop/facilitators.rst b/doc/workshop/facilitators.rst
@@ -30,6 +30,6 @@ Example: https://goo.gl/forms/UOkcsVROqV
 Vagrant boxes
 -------------
 
-See ``building.rst`` for instructions on building Vagrant boxes.
+See :ref:`building` for instructions on building Vagrant boxes.
 At time of writing, the ``freeipa/freeipa-workshop`` box is
 FreeIPA 4.9.3 / Fedora 34, for the VirtualBox and libvirt providers.
diff --git a/doc/workshop/workshop.rst b/doc/workshop/workshop.rst
@@ -1,4 +1,5 @@
-..
+.. _workshop:
+
   Copyright 2015, 2016  Red Hat, Inc.
 
   This work is licensed under the Creative Commons Attribution 4.0
@@ -18,27 +19,28 @@ X.509 certificates for services.
 
 .. _FreeIPA: http://www.freeipa.org/page/Main_Page
 
+.. _curriculum-overview:
 
 Curriculum overview
 -------------------
 
 Mandatory:
 
-- `Unit 1: Installing the FreeIPA server <1-server-install.rst>`_
-- `Unit 2: Enrolling client machines <2-client-install.rst>`_
-- `Unit 3: User management and Kerberos authentication <3-user-management.rst>`_
-- `Unit 4: Host-based access control (HBAC) <4-hbac.rst>`_
+- :ref:`Unit 1: Installing the FreeIPA server <1-server-install>`
+- :ref:`Unit 2: Enrolling client machines <2-client-install>`
+- :ref:`Unit 3: User management and Kerberos authentication <3-user-management>`
+- :ref:`Unit 4: Host-based access control (HBAC) <4-hbac>`
 
 Optional units—choose the topics that are relevant to you:
 
-- `Unit 5: Web application authentication and authorisation <5-web-app-authnz.rst>`_
-- `Unit 6: Service certificates <6-cert-management.rst>`_
-- `Unit 7: Replica installation <7-replica-install.rst>`_
-- `Unit 8: Sudo rule management <8-sudorule.rst>`_
-- `Unit 9: SELinux User Maps <9-selinux-user-map.rst>`_
-- `Unit 10: SSH user and host key management <10-ssh-key-management.rst>`_
-- `Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy.rst>`_
-- `Unit 12: External IdP support <12-external-idp-support.rst>`_
+- :ref:`Unit 5: Web application authentication and authorisation <5-web-app-authnz>`
+- :ref:`Unit 6: Service certificates <6-cert-management>`
+- :ref:`Unit 7: Replica installation <7-replica-install>`
+- :ref:`Unit 8: Sudo rule management <8-sudorule>`
+- :ref:`Unit 9: SELinux User Maps <9-selinux-user-map>`
+- :ref:`Unit 10: SSH user and host key management <10-ssh-key-management>`
+- :ref:`Unit 11: Kerberos ticket policy <11-kerberos-ticket-policy>`
+- :ref:`Unit 12: External IdP support <12-external-idp-support>`
 
 Editing files on VMs
 --------------------
@@ -241,7 +243,7 @@ Next step
 ---------
 
 You are ready to begin the workshop.  Continue to
-`Unit 1: Installing the FreeIPA server <1-server-install.rst>`_.
+:ref:`Unit 1: Installing the FreeIPA server <1-server-install>`.
 
 
 After the workshop