From df5d04ba440e0d1bc17871146cbab382040a2990 Mon Sep 17 00:00:00 2001
From: Ruth Fuchss <ruth.fuchss@canonical.com>
Date: Thu, 21 Sep 2023 11:58:55 +0200
Subject: [PATCH 1/2] doc: update topical navigation

Instead of using the Sphinx "only" directive in an unsupported way
to create to different navigation structures, use a "filtered-toc"
extension that actually supports this.
Update the existing navigation to use this new feature.
This also allows us to use the same index page for both navigations.

Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
---
 doc/clustering.md               | 42 +++++++++----------
 doc/custom_conf.py              | 18 +++++---
 doc/external_resources.md       |  1 +
 doc/getting_started.md          | 40 ++++++++----------
 doc/images.md                   | 36 ++++++++--------
 doc/index.md                    | 40 ++++++++++++++----
 doc/index_topical.md            | 74 ---------------------------------
 doc/instances.md                | 60 +++++++++++++-------------
 doc/internals.md                | 29 ++++++-------
 doc/migration.md                | 20 ++++-----
 doc/networks.md                 | 60 +++++++++++++-------------
 doc/operation.md                | 34 +++++++--------
 doc/production-setup.md         | 36 ++++++++--------
 doc/projects.md                 | 26 ++++++------
 doc/reference/network_bridge.md |  8 ++--
 doc/reference/network_ovn.md    | 10 ++---
 doc/storage.md                  | 38 ++++++++---------
 17 files changed, 252 insertions(+), 320 deletions(-)
 delete mode 100644 doc/index_topical.md

diff --git a/doc/clustering.md b/doc/clustering.md
index 99e2f3078ddc..23cb393329ee 100644
--- a/doc/clustering.md
+++ b/doc/clustering.md
@@ -5,21 +5,21 @@ discourse: 9076,15871
 (clustering)=
 # Clustering
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to clustering:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Configure networks </howto/cluster_config_networks>
-Configure storage </howto/cluster_config_storage>
-Form a cluster </howto/cluster_form>
-Manage a cluster </howto/cluster_manage>
-Manage instances </howto/cluster_manage_instance>
-Recover a cluster </howto/cluster_recover>
-Set up cluster groups </howto/cluster_groups>
+:diataxis:Configure networks </howto/cluster_config_networks>
+:diataxis:Configure storage </howto/cluster_config_storage>
+:diataxis:Form a cluster </howto/cluster_form>
+:diataxis:Manage a cluster </howto/cluster_manage>
+:diataxis:Manage instances </howto/cluster_manage_instance>
+:diataxis:Recover a cluster </howto/cluster_recover>
+:diataxis:Set up cluster groups </howto/cluster_groups>
 ```
-````
 
 ## Related topics
 
@@ -29,18 +29,16 @@ Set up cluster groups </howto/cluster_groups>
 {{clustering_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-/explanation/clustering.md
-Form a cluster </howto/cluster_form>
-Manage a cluster </howto/cluster_manage>
-Recover a cluster </howto/cluster_recover>
-Manage instances </howto/cluster_manage_instance>
-Configure storage </howto/cluster_config_storage>
-Configure networks </howto/cluster_config_networks>
-Set up cluster groups </howto/cluster_groups>
-/reference/cluster_member_config
+:topical:/explanation/clustering.md
+:topical:Form a cluster </howto/cluster_form>
+:topical:Manage a cluster </howto/cluster_manage>
+:topical:Recover a cluster </howto/cluster_recover>
+:topical:Manage instances </howto/cluster_manage_instance>
+:topical:Configure storage </howto/cluster_config_storage>
+:topical:Configure networks </howto/cluster_config_networks>
+:topical:Set up cluster groups </howto/cluster_groups>
+:topical:/reference/cluster_member_config
 ```
-````
diff --git a/doc/custom_conf.py b/doc/custom_conf.py
index a2b8c1472b48..f62defb4510f 100644
--- a/doc/custom_conf.py
+++ b/doc/custom_conf.py
@@ -1,5 +1,6 @@
 import datetime
 import os
+import sys
 import subprocess
 import yaml
 from git import Repo
@@ -136,7 +137,8 @@
 custom_extensions = [
     'sphinx.ext.intersphinx',
     'config-options',
-    'sphinx_remove_toctrees'
+    'sphinx_remove_toctrees',
+    'filtered-toc'
 ]
 
 # Add files or directories that should be excluded from processing.
@@ -301,12 +303,16 @@
 ### End MAN PAGES ###
 
 if ('TOPICAL' in os.environ) and (os.environ['TOPICAL'] == 'True'):
-    root_doc = 'index_topical'
-    custom_excludes.extend(['index.md','tutorial/index.md','howto/index.md','explanation/index.md','reference/index.md','howto/troubleshoot.md'])
-    redirects['index/index'] = '../index_topical/'
-    redirects['index'] = '../index_topical/'
+    custom_excludes.extend(['tutorial/index.md','howto/index.md','explanation/index.md','reference/index.md','howto/troubleshoot.md'])
+    redirects['index_topical/index'] = '../index.html'
+    redirects['index_topical'] = '../index.html'
     custom_tags.append('topical')
+    toc_filter_exclude = ['diataxis']
 else:
-    custom_excludes.extend(['index_topical.md','security.md','external_resources.md','reference/network_external.md'])
+    custom_excludes.extend(['security.md','external_resources.md','reference/network_external.md'])
     redirects['security/index'] = '../explanation/security/'
     custom_tags.append('diataxis')
+    toc_filter_exclude = ['topical']
+
+
+sys.path.append(os.path.abspath('.sphinx/_extensions/'))
diff --git a/doc/external_resources.md b/doc/external_resources.md
index 344910ae8fc6..5a42f191a1b1 100644
--- a/doc/external_resources.md
+++ b/doc/external_resources.md
@@ -1,3 +1,4 @@
+(troubleshoot)=
 # External resources
 
 ```{toctree}
diff --git a/doc/getting_started.md b/doc/getting_started.md
index 9b1dade606a2..1a13b43fa902 100644
--- a/doc/getting_started.md
+++ b/doc/getting_started.md
@@ -7,18 +7,16 @@ relatedlinks: https://www.youtube.com/watch?v=QyXOOE_4cm0
 
 To get started with LXD, see the documentation in this section.
 
-````{only} diataxis
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-Access the documentation </howto/access_documentation>
-Access the UI </howto/access_ui>
-Contribute to LXD </contributing>
-Get support </support>
-Initialize LXD </howto/initialize>
-Install LXD </installing>
+:diataxis:Access the documentation </howto/access_documentation>
+:diataxis:Access the UI </howto/access_ui>
+:diataxis:Contribute to LXD </contributing>
+:diataxis:Get support </support>
+:diataxis:Initialize LXD </howto/initialize>
+:diataxis:Install LXD </installing>
 ```
-````
 
 In addition, the following clip gives a quick and easy introduction for standard use cases:
 
@@ -40,19 +38,17 @@ You can also find a series of demos and tutorials on YouTube:
 {{getting_started_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/tutorial/first_steps
-/explanation/containers_and_vms
-/requirements
-Install LXD </installing>
-Initialize LXD </howto/initialize>
-Access the UI </howto/access_ui>
-Access the documentation </howto/access_documentation>
-Frequently asked </faq>
-Contribute to LXD </contributing>
-Get support </support>
+:topical:/tutorial/first_steps
+:topical:/explanation/containers_and_vms
+:topical:/requirements
+:topical:Install LXD </installing>
+:topical:Initialize LXD </howto/initialize>
+:topical:Access the UI </howto/access_ui>
+:topical:Access the documentation </howto/access_documentation>
+:topical:Frequently asked </faq>
+:topical:Contribute to LXD </contributing>
+:topical:Get support </support>
 ```
-````
diff --git a/doc/images.md b/doc/images.md
index 481a0cfe8179..1fa4ce30eb97 100644
--- a/doc/images.md
+++ b/doc/images.md
@@ -1,19 +1,19 @@
 (images)=
 # Images
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to images:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Associate profiles </howto/images_profiles>
-Copy and import images </howto/images_copy>
-Create images </howto/images_create>
-Manage images </howto/images_manage>
-Use remote images </howto/images_remote>
+:diataxis:Associate profiles </howto/images_profiles>
+:diataxis:Copy and import images </howto/images_copy>
+:diataxis:Create images </howto/images_create>
+:diataxis:Manage images </howto/images_manage>
+:diataxis:Use remote images </howto/images_remote>
 ```
-````
 
 ## Related topics
 
@@ -23,17 +23,15 @@ Use remote images </howto/images_remote>
 {{images_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/image-handling
-Use remote images </howto/images_remote>
-Manage images </howto/images_manage>
-Copy and import images </howto/images_copy>
-Create images </howto/images_create>
-Associate profiles </howto/images_profiles>
-/reference/remote_image_servers
-/reference/image_format
+:topical:/image-handling
+:topical:Use remote images </howto/images_remote>
+:topical:Manage images </howto/images_manage>
+:topical:Copy and import images </howto/images_copy>
+:topical:Create images </howto/images_create>
+:topical:Associate profiles </howto/images_profiles>
+:topical:/reference/remote_image_servers
+:topical:/reference/image_format
 ```
-````
diff --git a/doc/index.md b/doc/index.md
index fe02978ac315..f0db101b4395 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -18,6 +18,8 @@ LXD (<a href="#" title="Listen" onclick="document.getElementById('player').play(
 
 ## In this documentation
 
+`````{only} diataxis
+
 ````{grid} 1 1 2 2
 
 ```{grid-item} [Tutorials](tutorial/index)
@@ -47,6 +49,30 @@ LXD (<a href="#" title="Listen" onclick="document.getElementById('player').play(
 
 ````
 
+`````
+
+```{filtered-toctree}
+:titlesonly:
+:maxdepth: 1
+
+:topical:self
+:topical:getting_started
+:topical:Server and client <operation>
+:topical:security
+:topical:instances
+:topical:images
+:topical:storage
+:topical:networks
+:topical:projects
+:topical:clustering
+:topical:production-setup
+:topical:migration
+:topical:restapi_landing
+:topical:Internals & debugging <internals>
+:topical:external_resources
+:topical:Switch to Diataxis navigation <https://documentation.ubuntu.com/lxd/en/latest/>
+```
+
 ---
 
 ## Security
@@ -85,14 +111,14 @@ The LXD project is sponsored by [Canonical Ltd](https://www.canonical.com).
 - [Discuss on IRC](https://web.libera.chat/#lxd) (see [Getting started with IRC](https://discourse.ubuntu.com/t/getting-started-with-irc/37907) if needed)
 - [Ask and answer questions on the forum](https://discourse.ubuntu.com/c/lxd/)
 
-```{toctree}
+```{filtered-toctree}
 :hidden:
 :titlesonly:
 
-self
-tutorial/index
-howto/index
-explanation/index
-reference/index
-Switch to topical navigation <https://documentation.ubuntu.com/lxd/to/latest/index_topical/>
+:diataxis:self
+:diataxis:tutorial/index
+:diataxis:howto/index
+:diataxis:explanation/index
+:diataxis:reference/index
+:diataxis:Switch to topical navigation <https://documentation.ubuntu.com/lxd/to/latest/>
 ```
diff --git a/doc/index_topical.md b/doc/index_topical.md
deleted file mode 100644
index e7731019e27e..000000000000
--- a/doc/index_topical.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-relatedlinks: https://ubuntu.com/lxd, https://ubuntu.com/blog/open-source-for-beginners-dev-environment-with-lxd
----
-
-(index)=
-# LXD
-
-LXD (<a href="#" title="Listen" onclick="document.getElementById('player').play();return false;">`[lɛks'di:]`&#128264;</a>) is a modern, secure and powerful system container and virtual machine manager.
-
-<audio id="player">  <source src="_static/lxd.mp3" type="audio/mpeg">  <source src="_static/lxd.ogg" type="audio/ogg">  <source src="_static/lxd.wav" type="audio/wav"></audio>
-
-% Include content from [../README.md](../README.md)
-```{include} ../README.md
-    :start-after: <!-- Include start LXD intro -->
-    :end-before: <!-- Include end LXD intro -->
-```
-
-## Security
-
-% Include content from [../README.md](../README.md)
-```{include} ../README.md
-    :start-after: <!-- Include start security -->
-    :end-before: <!-- Include end security -->
-```
-
-See [Security](security.md) for detailed information.
-
-````{important}
-% Include content from [../README.md](../README.md)
-```{include} ../README.md
-    :start-after: <!-- Include start security note -->
-    :end-before: <!-- Include end security note -->
-```
-````
-
-(troubleshoot)=
-(community)=
-## Project and community
-
-LXD is free software and developed under the [Apache 2 license](https://www.apache.org/licenses/LICENSE-2.0).
-It’s an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
-
-The LXD project is sponsored by [Canonical Ltd](https://www.canonical.com).
-
-- [Code of Conduct](https://github.com/canonical/lxd/blob/main/CODE_OF_CONDUCT.md)
-- [Contribute to the project](contributing.md)
-- [Release announcements](https://discourse.ubuntu.com/c/lxd/news/)
-- [Release tarballs](https://github.com/canonical/lxd/releases/)
-- [Get support](support.md)
-- [Watch tutorials and announcements on YouTube](https://www.youtube.com/c/LXDvideos)
-- [Discuss on IRC](https://web.libera.chat/#lxd) (see [Getting started with IRC](https://discourse.ubuntu.com/t/getting-started-with-irc/37907) if needed)
-- [Ask and answer questions on the forum](https://discourse.ubuntu.com/c/lxd/)
-
-```{toctree}
-:hidden:
-:titlesonly:
-
-self
-getting_started
-Server and client <operation>
-security
-instances
-images
-storage
-networks
-projects
-clustering
-production-setup
-migration
-restapi_landing
-Internals & debugging <internals>
-external_resources
-Switch to Diataxis navigation <https://documentation.ubuntu.com/lxd/en/latest/>
-```
diff --git a/doc/instances.md b/doc/instances.md
index a2fb794edf14..b8a8e88800ac 100644
--- a/doc/instances.md
+++ b/doc/instances.md
@@ -5,25 +5,25 @@ relatedlinks: https://ubuntu.com/tutorials/how-to-install-a-windows-11-vm-using-
 (instances)=
 # Instances
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to instances:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Access files </howto/instances_access_files.md>
-Access the console </howto/instances_console.md>
-Add a routed NIC to a VM </howto/instances_routed_nic_vm.md>
-Back up instances </howto/instances_backup.md>
-Configure instances </howto/instances_configure.md>
-Create instances </howto/instances_create.md>
-Manage instances </howto/instances_manage.md>
-Run commands </instance-exec.md>
-Troubleshoot errors </howto/instances_troubleshoot.md>
-Use cloud-init </cloud-init>
-Use profiles </profiles.md>
+:diataxis:Access files </howto/instances_access_files.md>
+:diataxis:Access the console </howto/instances_console.md>
+:diataxis:Add a routed NIC to a VM </howto/instances_routed_nic_vm.md>
+:diataxis:Back up instances </howto/instances_backup.md>
+:diataxis:Configure instances </howto/instances_configure.md>
+:diataxis:Create instances </howto/instances_create.md>
+:diataxis:Manage instances </howto/instances_manage.md>
+:diataxis:Run commands </instance-exec.md>
+:diataxis:Troubleshoot errors </howto/instances_troubleshoot.md>
+:diataxis:Use cloud-init </cloud-init>
+:diataxis:Use profiles </profiles.md>
 ```
-````
 
 ## Related topics
 
@@ -33,23 +33,21 @@ Use profiles </profiles.md>
 {{instances_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-/explanation/instances.md
-Create instances </howto/instances_create.md>
-Manage instances </howto/instances_manage.md>
-Configure instances </howto/instances_configure.md>
-Back up instances </howto/instances_backup.md>
-Use profiles </profiles.md>
-Use cloud-init </cloud-init>
-Run commands </instance-exec.md>
-Access the console </howto/instances_console.md>
-Access files </howto/instances_access_files.md>
-Add a routed NIC to a VM </howto/instances_routed_nic_vm.md>
-Troubleshoot errors </howto/instances_troubleshoot.md>
-/explanation/instance_config.md
-Container environment </container-environment>
+:topical:/explanation/instances.md
+:topical:Create instances </howto/instances_create.md>
+:topical:Manage instances </howto/instances_manage.md>
+:topical:Configure instances </howto/instances_configure.md>
+:topical:Back up instances </howto/instances_backup.md>
+:topical:Use profiles </profiles.md>
+:topical:Use cloud-init </cloud-init>
+:topical:Run commands </instance-exec.md>
+:topical:Access the console </howto/instances_console.md>
+:topical:Access files </howto/instances_access_files.md>
+:topical:Add a routed NIC to a VM </howto/instances_routed_nic_vm.md>
+:topical:Troubleshoot errors </howto/instances_troubleshoot.md>
+:topical:/explanation/instance_config.md
+:topical:Container environment </container-environment>
 ```
-````
diff --git a/doc/internals.md b/doc/internals.md
index 70b131202056..acbf6d2d14ff 100644
--- a/doc/internals.md
+++ b/doc/internals.md
@@ -1,15 +1,13 @@
 # Internals
 
-````{only} diataxis
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-/daemon-behavior
-/environment
-/syscall-interception
-User namespace setup </userns-idmap>
+:diataxis:/daemon-behavior
+:diataxis:/environment
+:diataxis:/syscall-interception
+:diataxis:User namespace setup </userns-idmap>
 ```
-````
 
 ## Related topics
 
@@ -20,16 +18,13 @@ How-to guides:
 
 ```
 
-
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/daemon-behavior
-Debug LXD </debugging>
-/environment
-/syscall-interception
-User namespace setup </userns-idmap>
-Configuration option index </config-options>
+:topical:/daemon-behavior
+:topical:Debug LXD </debugging>
+:topical:/environment
+:topical:/syscall-interception
+:topical:User namespace setup </userns-idmap>
+:topical:Configuration option index </config-options>
 ```
-````
diff --git a/doc/migration.md b/doc/migration.md
index ba72f8a1fac4..67c3f7ebbe06 100644
--- a/doc/migration.md
+++ b/doc/migration.md
@@ -26,23 +26,21 @@ Migrate existing LXD instances between servers
 
 ````{only} diataxis
 The following how-to guides cover common operations related to migration:
+````
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Import existing machines </howto/import_machines_to_instances>
-Migrate from LXC </howto/migrate_from_lxc>
-Move instances </howto/move_instances>
+:diataxis:Import existing machines </howto/import_machines_to_instances>
+:diataxis:Migrate from LXC </howto/migrate_from_lxc>
+:diataxis:Move instances </howto/move_instances>
 ```
-````
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 :hidden:
 
-Move instances </howto/move_instances>
-Import existing machines </howto/import_machines_to_instances>
-Migrate from LXC </howto/migrate_from_lxc>
+:topical:Move instances </howto/move_instances>
+:topical:Import existing machines </howto/import_machines_to_instances>
+:topical:Migrate from LXC </howto/migrate_from_lxc>
 ```
-````
diff --git a/doc/networks.md b/doc/networks.md
index 1c6675031a91..c17e1a041814 100644
--- a/doc/networks.md
+++ b/doc/networks.md
@@ -5,40 +5,44 @@ discourse: 13021
 (networking)=
 # Networking
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to networking:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Configure a network </howto/network_configure>
-Configure as BGP server </howto/network_bgp>
-Configure forwards </howto/network_forwards>
-Configure network ACLs </howto/network_acls>
-Configure network zones </howto/network_zones>
-Create a network </howto/network_create>
-Display IPAM information </howto/network_ipam>
+:diataxis:Configure a network </howto/network_configure>
+:diataxis:Configure as BGP server </howto/network_bgp>
+:diataxis:Configure forwards </howto/network_forwards>
+:diataxis:Configure network ACLs </howto/network_acls>
+:diataxis:Configure network zones </howto/network_zones>
+:diataxis:Create a network </howto/network_create>
+:diataxis:Display IPAM information </howto/network_ipam>
 ```
 
+```{only} diataxis
 The following how-to guides apply to managed bridge networks only:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Configure your firewall </howto/network_bridge_firewalld>
-Integrate with resolved </howto/network_bridge_resolved>
+:diataxis:Configure your firewall </howto/network_bridge_firewalld>
+:diataxis:Integrate with resolved </howto/network_bridge_resolved>
 ```
 
+```{only} diataxis
 The following how-to guides apply to OVN networks only:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Configure load balancers </howto/network_load_balancers>
-Configure peer routing </howto/network_ovn_peers>
-Set up OVN </howto/network_ovn_setup>
+:diataxis:Configure load balancers </howto/network_load_balancers>
+:diataxis:Configure peer routing </howto/network_ovn_peers>
+:diataxis:Set up OVN </howto/network_ovn_setup>
 ```
-````
 
 ## Related topics
 
@@ -48,18 +52,16 @@ Set up OVN </howto/network_ovn_setup>
 {{networks_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/explanation/networks
-Create a network </howto/network_create>
-Configure a network </howto/network_configure>
-Configure network ACLs </howto/network_acls>
-Configure network forwards </howto/network_forwards>
-Configure network zones </howto/network_zones>
-Configure LXD as BGP server </howto/network_bgp>
-Display LXD IPAM information </howto/network_ipam>
-/reference/networks
+:topical:/explanation/networks
+:topical:Create a network </howto/network_create>
+:topical:Configure a network </howto/network_configure>
+:topical:Configure network ACLs </howto/network_acls>
+:topical:Configure network forwards </howto/network_forwards>
+:topical:Configure network zones </howto/network_zones>
+:topical:Configure LXD as BGP server </howto/network_bgp>
+:topical:Display LXD IPAM information </howto/network_ipam>
+:topical:/reference/networks
 ```
-````
diff --git a/doc/operation.md b/doc/operation.md
index 7388206e0f2e..b3aa15f1f8a9 100644
--- a/doc/operation.md
+++ b/doc/operation.md
@@ -1,18 +1,18 @@
 (lxd-server)=
 # LXD server and client
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to the LXD server and the LXD client:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Add command aliases </howto/lxc_alias>
-Add remote servers </remotes>
-Configure the LXD server </howto/server_configure>
-Expose LXD to the network </howto/server_expose>
+:diataxis:Add command aliases </howto/lxc_alias>
+:diataxis:Add remote servers </remotes>
+:diataxis:Configure the LXD server </howto/server_configure>
+:diataxis:Expose LXD to the network </howto/server_expose>
 ```
-````
 
 ## Related topics
 
@@ -22,17 +22,15 @@ Expose LXD to the network </howto/server_expose>
 {{server_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/explanation/lxd_lxc
-/database
-Configure the LXD server </howto/server_configure>
-Add remote servers </remotes>
-Add command aliases </howto/lxc_alias>
-/server
-/architectures
-/reference/manpages
+:topical:/explanation/lxd_lxc
+:topical:/database
+:topical:Configure the LXD server </howto/server_configure>
+:topical:Add remote servers </remotes>
+:topical:Add command aliases </howto/lxc_alias>
+:topical:/server
+:topical:/architectures
+:topical:/reference/manpages
 ```
-````
diff --git a/doc/production-setup.md b/doc/production-setup.md
index 74aa26587cfa..6ac25c6c19f9 100644
--- a/doc/production-setup.md
+++ b/doc/production-setup.md
@@ -1,18 +1,18 @@
 # Production setup
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to the LXD server and the LXD client:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Back up a server </backup>
-Benchmark performance </howto/benchmark_performance>
-Increase bandwidth </howto/network_increase_bandwidth>
-Monitor metrics </metrics>
-Recover instances </howto/disaster_recovery>
+:diataxis:Back up a server </backup>
+:diataxis:Benchmark performance </howto/benchmark_performance>
+:diataxis:Increase bandwidth </howto/network_increase_bandwidth>
+:diataxis:Monitor metrics </metrics>
+:diataxis:Recover instances </howto/disaster_recovery>
 ```
-````
 
 ## Related topics
 
@@ -22,17 +22,15 @@ Recover instances </howto/disaster_recovery>
 {{performance_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/explanation/performance_tuning
-Benchmark performance </howto/benchmark_performance>
-Monitor metrics </metrics>
-Increase bandwidth </howto/network_increase_bandwidth>
-Back up a server </backup>
-Recover instances </howto/disaster_recovery>
-Server settings </reference/server_settings>
-/reference/provided_metrics
+:topical:/explanation/performance_tuning
+:topical:Benchmark performance </howto/benchmark_performance>
+:topical:Monitor metrics </metrics>
+:topical:Increase bandwidth </howto/network_increase_bandwidth>
+:topical:Back up a server </backup>
+:topical:Recover instances </howto/disaster_recovery>
+:topical:Server settings </reference/server_settings>
+:topical:/reference/provided_metrics
 ```
-````
diff --git a/doc/projects.md b/doc/projects.md
index 15ed5c2e7a9f..4edd37b49494 100644
--- a/doc/projects.md
+++ b/doc/projects.md
@@ -5,17 +5,17 @@ relatedlinks: https://ubuntu.com/tutorials/introduction-to-lxd-projects
 (projects)=
 # Projects
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to projects:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Confine projects to users </howto/projects_confine>
-Create and configure </howto/projects_create>
-Work with projects </howto/projects_work>
+:diataxis:Confine projects to users </howto/projects_confine>
+:diataxis:Create and configure </howto/projects_create>
+:diataxis:Work with projects </howto/projects_work>
 ```
-````
 
 ## Related topics
 
@@ -25,14 +25,12 @@ Work with projects </howto/projects_work>
 {{projects_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 
-/explanation/projects
-Create and configure projects </howto/projects_create>
-Work with different projects </howto/projects_work>
-Confine projects to users </howto/projects_confine>
-reference/projects
+:topical:/explanation/projects
+:topical:Create and configure projects </howto/projects_create>
+:topical:Work with different projects </howto/projects_work>
+:topical:Confine projects to users </howto/projects_confine>
+:topical:/reference/projects
 ```
-````
diff --git a/doc/reference/network_bridge.md b/doc/reference/network_bridge.md
index d160b75c73cf..1d0dc50e0227 100644
--- a/doc/reference/network_bridge.md
+++ b/doc/reference/network_bridge.md
@@ -139,12 +139,10 @@ The following features are supported for the `bridge` network type:
 See {ref}`network-bridge-firewall` for instructions on how to troubleshoot firewall issues.
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 :hidden:
 
-Integrate with resolved </howto/network_bridge_resolved>
-Configure your firewall </howto/network_bridge_firewalld>
+:topical:Integrate with resolved </howto/network_bridge_resolved>
+:topical:Configure your firewall </howto/network_bridge_firewalld>
 ```
-````
diff --git a/doc/reference/network_ovn.md b/doc/reference/network_ovn.md
index 6f216e102d55..1ae25ed604ff 100644
--- a/doc/reference/network_ovn.md
+++ b/doc/reference/network_ovn.md
@@ -82,13 +82,11 @@ The following features are supported for the `ovn` network type:
 - {ref}`network-ovn-peers`
 - {ref}`network-load-balancers`
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :maxdepth: 1
 :hidden:
 
-Set up OVN </howto/network_ovn_setup>
-Create routing relationships </howto/network_ovn_peers>
-Configure network load balancers </howto/network_load_balancers>
+:topical:Set up OVN </howto/network_ovn_setup>
+:topical:Create routing relationships </howto/network_ovn_peers>
+:topical:Configure network load balancers </howto/network_load_balancers>
 ```
-````
diff --git a/doc/storage.md b/doc/storage.md
index 006bdd80b1cd..fab8b837a195 100644
--- a/doc/storage.md
+++ b/doc/storage.md
@@ -5,20 +5,20 @@ discourse: 7735
 (storage)=
 # Storage
 
-````{only} diataxis
+```{only} diataxis
 The following how-to guides cover common operations related to storage:
+```
 
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-Back up a volume </howto/storage_backup_volume>
-Create an instance in a pool </howto/storage_create_instance>
-Manage buckets </howto/storage_buckets>
-Manage pools </howto/storage_pools>
-Manage volumes </howto/storage_volumes>
-Move or copy a volume </howto/storage_move_volume>
+:diataxis:Back up a volume </howto/storage_backup_volume>
+:diataxis:Create an instance in a pool </howto/storage_create_instance>
+:diataxis:Manage buckets </howto/storage_buckets>
+:diataxis:Manage pools </howto/storage_pools>
+:diataxis:Manage volumes </howto/storage_volumes>
+:diataxis:Move or copy a volume </howto/storage_move_volume>
 ```
-````
 
 ## Related topics
 
@@ -28,17 +28,15 @@ Move or copy a volume </howto/storage_move_volume>
 {{storage_ref}}
 ```
 
-````{only} topical
-```{toctree}
+```{filtered-toctree}
 :titlesonly:
 
-About storage </explanation/storage>
-Manage pools </howto/storage_pools>
-Create an instance in a pool </howto/storage_create_instance>
-Manage volumes </howto/storage_volumes>
-Move or copy a volume </howto/storage_move_volume>
-Back up a volume </howto/storage_backup_volume>
-Manage buckets </howto/storage_buckets>
-/reference/storage_drivers
+:topical:About storage </explanation/storage>
+:topical:Manage pools </howto/storage_pools>
+:topical:Create an instance in a pool </howto/storage_create_instance>
+:topical:Manage volumes </howto/storage_volumes>
+:topical:Move or copy a volume </howto/storage_move_volume>
+:topical:Back up a volume </howto/storage_backup_volume>
+:topical:Manage buckets </howto/storage_buckets>
+:topical:/reference/storage_drivers
 ```
-````

From 1c57a8bdce52c493e35a42ed30f215dfe107e9aa Mon Sep 17 00:00:00 2001
From: Ruth Fuchss <ruth.fuchss@canonical.com>
Date: Thu, 21 Sep 2023 12:00:51 +0200
Subject: [PATCH 2/2] doc: unpin Sphinx version

The new extension works with any Sphinx version, so no need to keep
the version pinned.

Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
---
 doc/.sphinx/requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/.sphinx/requirements.txt b/doc/.sphinx/requirements.txt
index 3321cb79091b..7cc6303ac136 100644
--- a/doc/.sphinx/requirements.txt
+++ b/doc/.sphinx/requirements.txt
@@ -4,7 +4,7 @@ linkify-it-py
 lxd-sphinx-extensions
 myst-parser
 pyspelling
-sphinx==7.1.2
+sphinx
 sphinx-autobuild
 sphinx-copybutton
 sphinx-design