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 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 -Configure storage -Form a cluster -Manage a cluster -Manage instances -Recover a cluster -Set up cluster groups +:diataxis:Configure networks +:diataxis:Configure storage +:diataxis:Form a cluster +:diataxis:Manage a cluster +:diataxis:Manage instances +:diataxis:Recover a cluster +:diataxis:Set up cluster groups ``` -```` ## Related topics @@ -29,18 +29,16 @@ Set up cluster groups {{clustering_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :titlesonly: -/explanation/clustering.md -Form a cluster -Manage a cluster -Recover a cluster -Manage instances -Configure storage -Configure networks -Set up cluster groups -/reference/cluster_member_config +:topical:/explanation/clustering.md +:topical:Form a cluster +:topical:Manage a cluster +:topical:Recover a cluster +:topical:Manage instances +:topical:Configure storage +:topical:Configure networks +:topical:Set up 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 -Access the UI -Contribute to LXD -Get support -Initialize LXD -Install LXD +:diataxis:Access the documentation +:diataxis:Access the UI +:diataxis:Contribute to LXD +:diataxis:Get support +:diataxis:Initialize LXD +:diataxis:Install LXD ``` -```` 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 -Initialize LXD -Access the UI -Access the documentation -Frequently asked -Contribute to LXD -Get support +:topical:/tutorial/first_steps +:topical:/explanation/containers_and_vms +:topical:/requirements +:topical:Install LXD +:topical:Initialize LXD +:topical:Access the UI +:topical:Access the documentation +:topical:Frequently asked +:topical:Contribute to LXD +:topical:Get 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 -Copy and import images -Create images -Manage images -Use remote images +:diataxis:Associate profiles +:diataxis:Copy and import images +:diataxis:Create images +:diataxis:Manage images +:diataxis:Use remote images ``` -```` ## Related topics @@ -23,17 +23,15 @@ Use remote images {{images_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 -/image-handling -Use remote images -Manage images -Copy and import images -Create images -Associate profiles -/reference/remote_image_servers -/reference/image_format +:topical:/image-handling +:topical:Use remote images +:topical:Manage images +:topical:Copy and import images +:topical:Create images +:topical:Associate 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 (`[lɛks'di:]`🔈) is a modern, secure and powerful system container and virtual machine manager. - - - -% Include content from [../README.md](../README.md) -```{include} ../README.md - :start-after: - :end-before: -``` - -## Security - -% Include content from [../README.md](../README.md) -```{include} ../README.md - :start-after: - :end-before: -``` - -See [Security](security.md) for detailed information. - -````{important} -% Include content from [../README.md](../README.md) -```{include} ../README.md - :start-after: - :end-before: -``` -```` - -(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 -security -instances -images -storage -networks -projects -clustering -production-setup -migration -restapi_landing -Internals & debugging -external_resources -Switch to Diataxis navigation -``` 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 -Access the console -Add a routed NIC to a VM -Back up instances -Configure instances -Create instances -Manage instances -Run commands -Troubleshoot errors -Use cloud-init -Use profiles +:diataxis:Access files +:diataxis:Access the console +:diataxis:Add a routed NIC to a VM +:diataxis:Back up instances +:diataxis:Configure instances +:diataxis:Create instances +:diataxis:Manage instances +:diataxis:Run commands +:diataxis:Troubleshoot errors +:diataxis:Use cloud-init +:diataxis:Use profiles ``` -```` ## Related topics @@ -33,23 +33,21 @@ Use profiles {{instances_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :titlesonly: -/explanation/instances.md -Create instances -Manage instances -Configure instances -Back up instances -Use profiles -Use cloud-init -Run commands -Access the console -Access files -Add a routed NIC to a VM -Troubleshoot errors -/explanation/instance_config.md -Container environment +:topical:/explanation/instances.md +:topical:Create instances +:topical:Manage instances +:topical:Configure instances +:topical:Back up instances +:topical:Use profiles +:topical:Use cloud-init +:topical:Run commands +:topical:Access the console +:topical:Access files +:topical:Add a routed NIC to a VM +:topical:Troubleshoot errors +:topical:/explanation/instance_config.md +:topical: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 +:diataxis:/daemon-behavior +:diataxis:/environment +:diataxis:/syscall-interception +:diataxis:User namespace setup ``` -```` ## Related topics @@ -20,16 +18,13 @@ How-to guides: ``` - -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 -/daemon-behavior -Debug LXD -/environment -/syscall-interception -User namespace setup -Configuration option index +:topical:/daemon-behavior +:topical:Debug LXD +:topical:/environment +:topical:/syscall-interception +:topical:User namespace setup +:topical:Configuration option index ``` -```` 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 -Migrate from LXC -Move instances +:diataxis:Import existing machines +:diataxis:Migrate from LXC +:diataxis:Move instances ``` -```` -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 :hidden: -Move instances -Import existing machines -Migrate from LXC +:topical:Move instances +:topical:Import existing machines +:topical: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 -Configure as BGP server -Configure forwards -Configure network ACLs -Configure network zones -Create a network -Display IPAM information +:diataxis:Configure a network +:diataxis:Configure as BGP server +:diataxis:Configure forwards +:diataxis:Configure network ACLs +:diataxis:Configure network zones +:diataxis:Create a network +:diataxis:Display IPAM information ``` +```{only} diataxis The following how-to guides apply to managed bridge networks only: +``` -```{toctree} +```{filtered-toctree} :titlesonly: -Configure your firewall -Integrate with resolved +:diataxis:Configure your firewall +:diataxis:Integrate with resolved ``` +```{only} diataxis The following how-to guides apply to OVN networks only: +``` -```{toctree} +```{filtered-toctree} :titlesonly: -Configure load balancers -Configure peer routing -Set up OVN +:diataxis:Configure load balancers +:diataxis:Configure peer routing +:diataxis:Set up OVN ``` -```` ## Related topics @@ -48,18 +52,16 @@ Set up OVN {{networks_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 -/explanation/networks -Create a network -Configure a network -Configure network ACLs -Configure network forwards -Configure network zones -Configure LXD as BGP server -Display LXD IPAM information -/reference/networks +:topical:/explanation/networks +:topical:Create a network +:topical:Configure a network +:topical:Configure network ACLs +:topical:Configure network forwards +:topical:Configure network zones +:topical:Configure LXD as BGP server +:topical:Display LXD IPAM information +: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 -Add remote servers -Configure the LXD server -Expose LXD to the network +:diataxis:Add command aliases +:diataxis:Add remote servers +:diataxis:Configure the LXD server +:diataxis:Expose LXD to the network ``` -```` ## Related topics @@ -22,17 +22,15 @@ Expose LXD to the network {{server_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 -/explanation/lxd_lxc -/database -Configure the LXD server -Add remote servers -Add command aliases -/server -/architectures -/reference/manpages +:topical:/explanation/lxd_lxc +:topical:/database +:topical:Configure the LXD server +:topical:Add remote servers +:topical:Add command aliases +: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 -Benchmark performance -Increase bandwidth -Monitor metrics -Recover instances +:diataxis:Back up a server +:diataxis:Benchmark performance +:diataxis:Increase bandwidth +:diataxis:Monitor metrics +:diataxis:Recover instances ``` -```` ## Related topics @@ -22,17 +22,15 @@ Recover instances {{performance_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 -/explanation/performance_tuning -Benchmark performance -Monitor metrics -Increase bandwidth -Back up a server -Recover instances -Server settings -/reference/provided_metrics +:topical:/explanation/performance_tuning +:topical:Benchmark performance +:topical:Monitor metrics +:topical:Increase bandwidth +:topical:Back up a server +:topical:Recover instances +:topical: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 -Create and configure -Work with projects +:diataxis:Confine projects to users +:diataxis:Create and configure +:diataxis:Work with projects ``` -```` ## Related topics @@ -25,14 +25,12 @@ Work with projects {{projects_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :maxdepth: 1 -/explanation/projects -Create and configure projects -Work with different projects -Confine projects to users -reference/projects +:topical:/explanation/projects +:topical:Create and configure projects +:topical:Work with different projects +:topical:Confine projects to users +: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 -Configure your firewall +:topical:Integrate with resolved +:topical:Configure your firewall ``` -```` 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 -Create routing relationships -Configure network load balancers +:topical:Set up OVN +:topical:Create routing relationships +:topical:Configure 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 -Create an instance in a pool -Manage buckets -Manage pools -Manage volumes -Move or copy a volume +:diataxis:Back up a volume +:diataxis:Create an instance in a pool +:diataxis:Manage buckets +:diataxis:Manage pools +:diataxis:Manage volumes +:diataxis:Move or copy a volume ``` -```` ## Related topics @@ -28,17 +28,15 @@ Move or copy a volume {{storage_ref}} ``` -````{only} topical -```{toctree} +```{filtered-toctree} :titlesonly: -About storage -Manage pools -Create an instance in a pool -Manage volumes -Move or copy a volume -Back up a volume -Manage buckets -/reference/storage_drivers +:topical:About storage +:topical:Manage pools +:topical:Create an instance in a pool +:topical:Manage volumes +:topical:Move or copy a volume +:topical:Back up a volume +:topical:Manage buckets +:topical:/reference/storage_drivers ``` -````