KU-1983 Navigation (#783)

* navigation rework Co-authored-by: Nick Veitch <[email protected]>
canonical · Nov 11, 2024 · 13689bd · 13689bd
1 parent f6ef548
commit 13689bd
Show file tree

Hide file tree

Showing 41 changed files with 143 additions and 103 deletions.
diff --git a/docs/canonicalk8s/about.md b/docs/canonicalk8s/about.md
@@ -0,0 +1,2 @@
+```{include} src/snap/explanation/about.md
+```
diff --git a/docs/canonicalk8s/community.md b/docs/canonicalk8s/community.md
@@ -0,0 +1,2 @@
+```{include} src/snap/reference/community.md
+```
diff --git a/docs/canonicalk8s/index.md b/docs/canonicalk8s/index.md
@@ -19,48 +19,24 @@ Home <self>
 :hidden:
 :titlesonly:
 :maxdepth: 6
-:caption: Deploy from Snap package
-Overview <src/snap/index.md>
-src/snap/tutorial/index
-src/snap/howto/index
-src/snap/explanation/index
-src/snap/reference/index
-```
 
-```{toctree}
-:hidden:
-:caption: Deploy with Juju
-:titlesonly:
-:glob:
-Overview <src/charm/index>
-src/charm/tutorial/index
-src/charm/howto/index
-src/charm/explanation/index
-src/charm/reference/index
-```
+about.md
+Deploy from Snap package <src/snap/index.md>
+Deploy with Juju <src/charm/index.md>
+Deploy with Cluster API <src/capi/index.md>
+Community <community.md>
+Release notes <release.md>
 
-```{toctree}
-:hidden:
-:caption: Deploy with Cluster API (WIP)
-:titlesonly:
-:glob:
-Overview <src/capi/index>
-src/capi/tutorial/index
-src/capi/howto/index
-src/capi/explanation/index
-src/capi/reference/index
 ```
 
----
-
 ````{grid} 1 1 2 2
 
 ```{grid-item-card}
 :link: src/snap/
 ### [Install K8s from a snap ›](src/snap/index)
 ^^^
 Our tutorials, How To guides and other pages will explain how to install,
- configure and use the {{product}} 'k8s' snap.
+ configure and use the {{product}} 'k8s' snap. This is a great option if you are new to Kubernetes.
 ```
 
 ```{grid-item-card}
@@ -79,6 +55,14 @@ Our tutorials, How To guides and other pages will explain how to install,
 Our tutorials, guides and explanation pages will explain how to install,
  configure and use {{product}} through CAPI.
 ```
+
+```{grid-item-card}
+:link: about
+### [Overview of {{product}} ›](about)
+^^^
+Find out more about {{product}}, what services are included and get the
+answers to some common questions.
+```
 ````
 
 ---
@@ -104,5 +88,5 @@ and constructive feedback.
 [community]: src/snap/reference/community
 [contribute]: src/snap/howto/contribute
 [roadmap]: src/snap/reference/roadmap
-[overview page]: src/snap/explanation/about
+[overview page]: about
 [architecture documentation]: src/snap/reference/architecture
diff --git a/docs/canonicalk8s/release.md b/docs/canonicalk8s/release.md
@@ -0,0 +1,2 @@
+```{include} src/snap/reference/releases.md
+```
diff --git a/docs/src/_parts/template-tutorial b/docs/src/_parts/template-tutorial
@@ -68,7 +68,7 @@ workload and remove everything again!
 
 ## Next Steps
 
-- Keep mastering Canonical Kubernetes with kubectl: [How to use kubectl]
+- How to control {{product}} with `kubectl`: [How to use kubectl]
 - Explore Kubernetes commands with our [Command Reference Guide]
 - Learn how to set up a multi-node environment [Setting up a K8s cluster]
 - Configure storage options [Storage]

diff --git a/docs/src/capi/howto/index.md b/docs/src/capi/howto/index.md
@@ -14,7 +14,7 @@ Overview <self>
 :glob:
 :titlesonly:
 
-external-etcd
+Use external etcd <external-etcd.md>
 rollout-upgrades
 in-place-upgrades
 upgrade-providers

diff --git a/docs/src/capi/index.md b/docs/src/capi/index.md
@@ -1,5 +1,22 @@
 # Installing {{product}} with Cluster API
 
+```{toctree}
+:hidden:
+Overview <self>
+```
+
+```{toctree}
+:hidden:
+:titlesonly:
+:glob:
+:caption: Deploy with Cluster API
+Overview <index.md>
+tutorial/index.md
+howto/index.md
+explanation/index.md
+reference/index.md
+```
+
 Cluster API (CAPI) is a Kubernetes project focused on providing declarative APIs and tooling to simplify provisioning, upgrading, and operating multiple Kubernetes clusters. The supporting infrastructure, like virtual machines, networks, load balancers, and VPCs, as well as the cluster configuration are all defined in the same way that cluster operators are already familiar with. {{product}} supports deploying and operating Kubernetes through CAPI.
 
 ![Illustration depicting working on components and clouds][logo]

diff --git a/docs/src/capi/reference/index.md b/docs/src/capi/reference/index.md
@@ -12,7 +12,7 @@ Overview <self>
 :titlesonly:
 releases
 annotations
-community
+Community <community>
 configs
 
 ```

diff --git a/docs/src/charm/explanation/index.md b/docs/src/charm/explanation/index.md
@@ -39,4 +39,4 @@ details or information such as the command reference or release notes.
 [Tutorials section]: ../tutorial/index
 [How-to guides]:     ../howto/index
 [Reference section]: ../reference/index
-[explanation topic]: ../explanation/index.md
+[explanation topic]: ../../snap/explanation/index.md
diff --git a/docs/src/charm/howto/index.md b/docs/src/charm/howto/index.md
@@ -16,7 +16,7 @@ Overview <self>
 
 charm
 install-lxd
-etcd
+Integrate with etcd <etcd>
 proxy
 cos-lite
 contribute

diff --git a/docs/src/charm/index.md b/docs/src/charm/index.md
@@ -1,5 +1,22 @@
 # {{product}} charm documentation
 
+```{toctree}
+:hidden:
+Overview <self>
+```
+
+```{toctree}
+:hidden:
+:titlesonly:
+:caption: Deploy with Juju
+
+Overview <charm/index.md>
+tutorial/index.md
+howto/index.md
+explanation/index.md
+reference/index.md
+```
+
 The {{product}} charm, `k8s`, is an operator: software which wraps an
 application and contains all of the instructions necessary for deploying,
 configuring, scaling, integrating the application on any cloud supported by
@@ -66,10 +83,10 @@ and constructive feedback.
 <!-- LINKS -->
 
 [Code of Conduct]: https://ubuntu.com/community/ethos/code-of-conduct
-[community]: /charm/reference/community
-[contribute]: /snap/howto/contribute
-[roadmap]: /snap/reference/roadmap
-[overview page]: /charm/explanation/about
-[arch]: /charm/reference/architecture
+[community]: reference/community
+[contribute]: ../snap/howto/contribute
+[roadmap]: ../snap/reference/roadmap
+[overview page]: explanation/about
+[arch]: reference/architecture
 [Juju]: https://juju.is
-[k8s snap package]: /snap/index
+[k8s snap package]: ../snap/index
diff --git a/docs/src/charm/reference/charms.md b/docs/src/charm/reference/charms.md
@@ -29,7 +29,7 @@ implementation.
 
 <!-- LINKS -->
 [Juju]: https://juju.is
-[explaining channels]: /charm/explanation/channels
+[explaining channels]: ../explanation/channels
 [cs-k8s]: https://charmhub.io/k8s
 [cs-k8s-worker]: https://charmhub.io/k8s-worker
 [readme file]: https://github.com/canonical/k8s-operator#readme

diff --git a/docs/src/charm/reference/index.md b/docs/src/charm/reference/index.md
@@ -15,7 +15,7 @@ releases
 charms
 proxy
 architecture
-community
+Community <community>
 
 ```
 

diff --git a/docs/src/charm/tutorial/getting-started.md b/docs/src/charm/tutorial/getting-started.md
@@ -239,5 +239,5 @@ informed of updates.
 [Juju client]: https://juju.is/docs/juju/install-and-manage-the-client
 [Juju tutorial]: https://juju.is/docs/juju/tutorial
 [Kubectl]: https://kubernetes.io/docs/reference/kubectl/
-[the channel explanation page]: /snap/explanation/channels
-[releases page]: /charm/reference/releases
+[the channel explanation page]: ../../snap/explanation/channels
+[releases page]: ../reference/releases
diff --git a/docs/src/snap/explanation/epa.md b/docs/src/snap/explanation/epa.md
@@ -543,5 +543,5 @@ components and their roles:
 <!-- LINKS -->
 
 [no_hz]: https://www.kernel.org/doc/Documentation/timers/NO_HZ.txt
-[howto-epa]: /snap/howto/epa
+[howto-epa]: ../howto/epa
 
diff --git a/docs/src/snap/explanation/ingress.md b/docs/src/snap/explanation/ingress.md
@@ -78,8 +78,8 @@ outlining rules that direct traffic to your application's Kubernetes service.
 
 <!-- LINKS -->
 
-[Ingress]: /snap/howto/networking/default-ingress
-[Network]: /snap/howto/networking/default-network
+[Ingress]: ../howto/networking/default-ingress
+[Network]: ../howto/networking/default-network
 [Cilium]: https://cilium.io/
 [network plugin]: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/
 [Service]: https://kubernetes.io/docs/concepts/services-networking/service/

diff --git a/docs/src/snap/howto/cis-hardening.md b/docs/src/snap/howto/cis-hardening.md
@@ -286,7 +286,7 @@ the sets, including the dqlite specific checks in the output.
 [Center for Internet Security (CIS)]:https://www.cisecurity.org/
 [kube-bench]:https://aquasecurity.github.io/kube-bench/v0.6.15/
 [CIS Kubernetes Benchmark]:https://www.cisecurity.org/benchmark/kubernetes
-[getting-started-guide]: /snap/tutorial/getting-started
+[getting-started-guide]: ../tutorial/getting-started
 [kube-bench release]: https://github.com/aquasecurity/kube-bench/releases
 [upstream instructions]:https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/
 [rate limits]:https://kubernetes.io/docs/reference/config-api/apiserver-eventratelimit.v1alpha1
diff --git a/docs/src/snap/howto/epa.md b/docs/src/snap/howto/epa.md
@@ -1141,8 +1141,8 @@ the correct PCI address:
 <!-- LINKS -->
 
 [MAAS]: https://maas.io
-[channel]: https://documentation.ubuntu.com/canonical-kubernetes/latest/snap/explanation/channels/
-[install-link]: /snap/howto/install/snap
+[channel]: ../explanation/channels/
+[install-link]: install/snap
 [snap]: https://snapcraft.io/docs
 [cyclictest]: https://github.com/jlelli/rt-tests
-[explain-epa]: /snap/explanation/epa
+[explain-epa]: ../explanation/epa
diff --git a/docs/src/snap/howto/index.md b/docs/src/snap/howto/index.md
@@ -17,16 +17,15 @@ Overview <self>
 install/index
 networking/index
 storage/index
-external-datastore
-proxy
+Use an external datastore <external-datastore>
 backup-restore
 refresh-certs
 restore-quorum
 two-node-ha
-epa
+Set up Enhanced Platform Awareness <epa>
 cis-hardening
 contribute
-support
+Get support <support>
 ```
 
 ---

diff --git a/docs/src/snap/howto/install/index.md b/docs/src/snap/howto/install/index.md
@@ -12,8 +12,8 @@ the current How-to guides below.
 :glob:
 :titlesonly:
 
-snap
+Install from a snap <snap.md>
 multipass
-lxd
-offline
+Install in LXD <lxd.md>
+Install in air-gapped environments <offline.md>
 ```
diff --git a/docs/src/snap/howto/install/lxd.md b/docs/src/snap/howto/install/lxd.md
@@ -239,4 +239,4 @@ need to access for example storage devices (See comment in [^5]).
 [default-bridged-networking]: https://ubuntu.com/blog/lxd-networking-lxdbr0-explained
 [Microbot]: https://github.com/dontrebootme/docker-microbot
 [AppArmor]: https://apparmor.net/
-[channels]: /snap/explanation/channels
+[channels]: ../../explanation/channels
diff --git a/docs/src/snap/howto/install/offline.md b/docs/src/snap/howto/install/offline.md
@@ -29,7 +29,7 @@ are necessary to verify the integrity of the packages.
 ```{note}
 Update the version of k8s by adjusting the channel parameter.
 For more information on channels visit the
-[channels explanation](/snap/explanation/channels.md).
+[channels explanation](../../explanation/channels.md).
 ```
 
 ```{note}
@@ -299,11 +299,10 @@ After a while, confirm that all the cluster nodes show up in the output of the
 <!-- LINKS -->
 
 [Core20]: https://canonical.com/blog/ubuntu-core-20-secures-linux-for-iot
-[svc-ports]: /snap/explanation/services-and-ports.md
-[proxy]: /snap/howto/proxy.md
+[proxy]: ../networking/proxy.md
 [sync-images-yaml]: https://github.com/canonical/k8s-snap/blob/main/build-scripts/hack/sync-images.yaml
 [regsync]: https://github.com/regclient/regclient/blob/main/docs/regsync.md
 [regctl]: https://github.com/regclient/regclient/blob/main/docs/regctl.md
 [regctl.sh]: https://github.com/canonical/k8s-snap/blob/main/src/k8s/tools/regctl.sh
-[nodes]: /snap/tutorial/add-remove-nodes.md
+[nodes]: ../../tutorial/add-remove-nodes.md
 [squid]: https://www.squid-cache.org/
diff --git a/docs/src/snap/howto/install/snap.md b/docs/src/snap/howto/install/snap.md
@@ -80,4 +80,4 @@ ready state.
 [channels page]: ../../explanation/channels
 [snap]: https://snapcraft.io/docs
 [snapd support]: https://snapcraft.io/docs/installing-snapd
-[bootstrap]: /snap/reference/bootstrap-config-reference
+[bootstrap]: ../../reference/bootstrap-config-reference
diff --git a/docs/src/snap/howto/networking/default-dns.md b/docs/src/snap/howto/networking/default-dns.md
@@ -94,4 +94,4 @@ sudo k8s help disable
 
 <!-- LINKS -->
 
-[getting-started-guide]: /snap/tutorial/getting-started
+[getting-started-guide]: ../../tutorial/getting-started
diff --git a/docs/src/snap/howto/networking/default-ingress.md b/docs/src/snap/howto/networking/default-ingress.md
@@ -107,5 +107,5 @@ sudo k8s help disable
 
 [kubectl-create-secret-tls/]: https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_tls/
 [proxy-protocol]: https://kubernetes.io/docs/reference/networking/service-protocols/#protocol-proxy-special
-[getting-started-guide]: /snap/tutorial/getting-started
-[kubectl-guide]: /snap/tutorial/kubectl
+[getting-started-guide]: ../../tutorial/getting-started
+[kubectl-guide]: ../../tutorial/kubectl
diff --git a/docs/src/snap/howto/networking/default-loadbalancer.md b/docs/src/snap/howto/networking/default-loadbalancer.md
@@ -82,4 +82,4 @@ sudo k8s disable load-balancer
 <!-- LINKS -->
 
 [cidr]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing
-[getting-started-guide]: /snap/tutorial/getting-started
+[getting-started-guide]: ../../tutorial/getting-started
diff --git a/docs/src/snap/howto/networking/default-network.md b/docs/src/snap/howto/networking/default-network.md
@@ -91,4 +91,4 @@ sudo k8s disable network --help
 
 <!-- LINKS -->
 
-[getting-started-guide]: /snap/tutorial/getting-started
+[getting-started-guide]: ../../tutorial/getting-started
diff --git a/docs/src/snap/howto/networking/index.md b/docs/src/snap/howto/networking/index.md
@@ -11,10 +11,11 @@ how to configure and use key capabilities of {{product}}.
 ```{toctree}
 :titlesonly:
 
-default-dns.md
-default-network.md
-default-ingress.md
-default-loadbalancer.md
-dualstack.md
-ipv6.md
+Use default DNS <default-dns.md>
+Use default network <default-network.md>
+Use default Ingress <default-ingress.md>
+Use default load-balancer <default-loadbalancer.md>
+Enable Dual-Stack networking <dualstack.md>
+Set up an IPv6-only cluster <ipv6.md>
+Configure proxy settings <proxy.md>
 ```
diff --git a/docs/src/snap/howto/networking/ipv6.md b/docs/src/snap/howto/networking/ipv6.md
@@ -1,4 +1,4 @@
-# How to Setup an IPv6-Only Cluster
+# How to set up an IPv6-Only Cluster
 
 An IPv6-only Kubernetes cluster operates exclusively using IPv6 addresses,
 without support for IPv4. This configuration is ideal for environments that

diff --git a/docs/src/snap/howto/proxy.md → docs/src/snap/howto/networking/proxy.md b/docs/src/snap/howto/proxy.md → docs/src/snap/howto/networking/proxy.md
@@ -53,5 +53,5 @@ see the [documentation for adding proxy configuration via Juju][juju-proxy].
 
 <!-- LINKS -->
 
-[juju-proxy]: /charm/howto/proxy
+[juju-proxy]: ../../../charm/howto/proxy
 [squid]: https://ubuntu.com/server/docs/how-to-install-a-squid-server