Merge pull request #12288 from ru-fu/LXD-434-navigation-fix

Doc: fix for topical navigation

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

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
 ```
-````

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/'))

doc/external_resources.md

@@ -1,3 +1,4 @@
+(troubleshoot)=
 # External resources
 
 ```{toctree}

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>
 ```
-````

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
 ```
-````

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/>
 ```