Add capi docs structure (#539)

* fix code parsing error

* add capi section

docs/src/capi/explanation/index.md

@@ -0,0 +1,38 @@
+# Explanation
+
+For a better understanding of how Canonical Kubernetes works and related
+topics such as security, these pages will help expand your knowledge and
+help you get the most out of Kubernetes.
+
+```{toctree}
+:hidden:
+Overview <self>
+```
+
+```{toctree}
+:titlesonly:
+
+```
+
+
+
+---
+
+## Other documentation types
+
+If you are just getting started, the [Tutorials section] contains
+step-by-step tutorials to help guide you through exploring and using
+Canonical Kubernetes.
+
+If you have a specific goal our [How-to guides] have more in-depth
+detail than tutorials and can be applied to a broader set of applications.
+They’ll help you achieve an end-result but may require you to understand and
+adapt the steps to fit your specific requirements.
+
+Finally, our [Reference section] is for when you need to check specific
+details or information such as the command reference or release notes.
+
+<!--LINKS -->
+[Tutorials section]: ../tutorial/index
+[How-to guides]:     ../howto/index
+[Reference section]: ../reference/index

docs/src/capi/howto/index.md

@@ -0,0 +1,40 @@
+# How-to guides
+
+If you have a specific goal, but are already familiar with Kubernetes, our
+How-to guides are more specific and contain less background information.
+They’ll help you achieve an end result but may require you to understand and
+adapt the steps to fit your specific requirements.
+
+```{toctree}
+:hidden:
+Overview <self>
+```
+
+```{toctree}
+:glob:
+:titlesonly:
+
+
+```
+
+---
+
+## Other documentation types
+
+Our Reference section is for when you need to check specific details or
+information such as the command reference or release notes.
+
+Alternatively, the [Tutorials section] contains step-by-step tutorials to help
+guide you through exploring and using Canonical Kubernetes.
+
+For a better understanding of how Canonical Kubernetes works and related topics
+such as security, our [Explanation section] helps you expand your knowledge
+and get the most out of Kubernetes.
+
+Finally, our [Reference section] is for when you need to check specific details
+or information such as the command reference or release notes.
+
+<!--LINKS -->
+[Tutorials section]: ../tutorial/index
+[Explanation section]: ../explanation/index
+[Reference section]: ../reference/index

docs/src/capi/index.md

@@ -0,0 +1,66 @@
+# Canonical Kubernetes 
+
+XxxxxX XXXxx Xxxxxxxxx xxxxx xxxx xx xxxxxxxx xxxx xxx xxx xxx xxxxxxxxxx xx
+xxx xxxxxx xxx XXX. Xxxx x xxxxx xx xxxxx xxxxx Xxxxxxx xx xxxx xxxxxx
+xxxxxxxxxxx xxx xxx xx xxxx x xxxxxxx xxx xxxxxxxx.
+
+![Illustration depicting working on components and clouds][logo]
+
+## In this documentation
+
+````{grid} 1 1 2 2
+
+```{grid-item-card} [Tutorial](tutorial/index)
+
+**Start here!** A hands-on introduction to Canonical K8s for new users
+```
+
+```{grid-item-card} [How-to guides](howto/index)
+
+**Step-by-step guides** covering key operations and common tasks
+```
+
+````
+
+````{grid} 1 1 2 2
+
+
+```{grid-item-card} [Reference](reference/index)
+
+**Technical information** - specifications, APIs, architecture
+```
+
+```{grid-item-card} [Explanation](explanation/index)
+
+**Discussion and clarification** of key topics
+```
+
+````
+
+---
+
+## Project and community
+
+Canonical Kubernetes is a member of the Ubuntu family. It's an open source
+project which welcomes community involvement, contributions, suggestions, fixes
+and constructive feedback.
+
+- Our [Code of Conduct]
+- Our [community]
+- How to [contribute]
+- Our development [roadmap]
+
+<!-- IMAGES -->
+
+[logo]: https://assets.ubuntu.com/v1/843c77b6-juju-at-a-glace.svg
+
+<!-- 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
+[Juju]: https://juju.is
+[k8s snap package]: /snap/index

docs/src/capi/reference/index.md

@@ -0,0 +1,34 @@
+# Reference
+
+Our Reference section is for when you need to check specific details or
+information such as the command reference or release notes.
+
+```{toctree}
+:hidden:
+Overview <self>
+```
+
+```{toctree}
+:titlesonly:
+
+
+```
+
+## Other documentation types
+
+Alternatively, the [Tutorials section] contains step-by-step tutorials to help
+guide you through exploring and using Canonical Kubernetes.
+
+If you have a specific goal our [How-to guides] have more in-depth detail than
+tutorials and can be applied to a broader set of applications. They’ll help you
+achieve an end-result but may require you to understand and adapt the steps to
+fit your specific requirements.
+
+Finally, for a better understanding of how Canonical Kubernetes works and
+related topics such as security, our [Explanation section] helps you to expand
+your knowledge and get the most out of Kubernetes.
+
+<!--LINKS -->
+[Tutorials section]: ../tutorial/index
+[How-to guides]: ../howto/index
+[Explanation section]: ../explanation/index

docs/src/capi/tutorial/getting-started.md

@@ -0,0 +1 @@
+# Install Canonical K8s with Cluster API

docs/src/capi/tutorial/index.md

@@ -0,0 +1,36 @@
+# Tutorials
+
+This section contains a step-by-step guide to help you start exploring how to
+install and use Canonical Kubernetes.
+
+```{toctree}
+:hidden:
+Overview <self>
+```
+
+```{toctree}
+:glob:
+:titlesonly:
+getting-started
+```
+
+---
+
+## Other documentation types
+
+If you have a specific goal our [How-to guides] have more in-depth detail than
+tutorials and can be applied to a broader set of applications. They’ll help you
+achieve an end-result but may require you to understand and adapt the steps to
+fit your specific requirements.
+
+For a better understanding of how Canonical Kubernetes works and related topics
+such as security, our [Explanation section] helps you to expand your knowledge
+and get the most out of Kubernetes.
+
+Finally, our [Reference section] is for when you need to check specific details
+or information such as the command reference or release notes.
+
+<!--LINKS -->
+[How-to guides]: ../howto/index
+[Explanation section]: ../explanation/index
+[Reference section]: ../reference/index

docs/src/index.md

@@ -39,6 +39,18 @@ charm/explanation/index
 charm/reference/index
 ```
 
+```{toctree}
+:hidden:
+:caption: Deploy with Cluster API (WIP)
+:titlesonly:
+:glob:
+Overview <capi/index>
+capi/tutorial/index
+capi/howto/index
+capi/explanation/index
+capi/reference/index
+```
+
 ---
 
 ````{grid} 1 1 2 2

docs/src/snap/reference/troubleshooting.md

@@ -11,7 +11,7 @@ The [kubeconfig file] generated by the `k8s kubectl` CLI can not be used to
 access the cluster from an external machine. The following error is seen when
 running `kubectl` with the invalid kubeconfig:
 
-```bash
+```
 ...
 E0412 08:36:06.404499  517166 memcache.go:265] couldn't get current server API group list: Get "https://127.0.0.1:6443/api?timeout=32s": dial tcp 127.0.0.1:6443: connect: connection refused
 The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?
@@ -32,6 +32,7 @@ are available on localhost endpoints.
 Use `k8s config` instead of `k8s kubectl config` to generate a kubeconfig file
 that is valid for use on external machines.
 
+
 <!-- LINKS -->
 
 [kubeconfig file]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/

docs/tools/custom_conf.py

@@ -25,7 +25,7 @@
 # The title you want to display for the documentation in the sidebar.
 # You might want to include a version number here.
 # To not display any title, set this option to an empty string.
-html_title = project + ' documentation'
+html_title = 'Canonical K8s'
 
 # The default value uses the current year as the copyright year.
 #