From 52f770704829e5e22710996d336034297c84203b Mon Sep 17 00:00:00 2001 From: Nick Veitch Date: Thu, 11 Jul 2024 14:49:24 +0100 Subject: [PATCH] Add capi docs structure (#539) * fix code parsing error * add capi section --- docs/src/capi/explanation/index.md | 38 +++++++++++++ docs/src/capi/howto/index.md | 40 +++++++++++++ docs/src/capi/index.md | 66 ++++++++++++++++++++++ docs/src/capi/reference/index.md | 34 +++++++++++ docs/src/capi/tutorial/getting-started.md | 1 + docs/src/capi/tutorial/index.md | 36 ++++++++++++ docs/src/index.md | 12 ++++ docs/src/snap/reference/troubleshooting.md | 3 +- docs/tools/custom_conf.py | 2 +- 9 files changed, 230 insertions(+), 2 deletions(-) create mode 100644 docs/src/capi/explanation/index.md create mode 100644 docs/src/capi/howto/index.md create mode 100644 docs/src/capi/index.md create mode 100644 docs/src/capi/reference/index.md create mode 100644 docs/src/capi/tutorial/getting-started.md create mode 100644 docs/src/capi/tutorial/index.md diff --git a/docs/src/capi/explanation/index.md b/docs/src/capi/explanation/index.md new file mode 100644 index 000000000..d065c1227 --- /dev/null +++ b/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 +``` + +```{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. + + +[Tutorials section]: ../tutorial/index +[How-to guides]: ../howto/index +[Reference section]: ../reference/index diff --git a/docs/src/capi/howto/index.md b/docs/src/capi/howto/index.md new file mode 100644 index 000000000..37dbed622 --- /dev/null +++ b/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 +``` + +```{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. + + +[Tutorials section]: ../tutorial/index +[Explanation section]: ../explanation/index +[Reference section]: ../reference/index diff --git a/docs/src/capi/index.md b/docs/src/capi/index.md new file mode 100644 index 000000000..814de5b9f --- /dev/null +++ b/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] + + + +[logo]: https://assets.ubuntu.com/v1/843c77b6-juju-at-a-glace.svg + + + +[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 \ No newline at end of file diff --git a/docs/src/capi/reference/index.md b/docs/src/capi/reference/index.md new file mode 100644 index 000000000..7db0080ff --- /dev/null +++ b/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 +``` + +```{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. + + +[Tutorials section]: ../tutorial/index +[How-to guides]: ../howto/index +[Explanation section]: ../explanation/index diff --git a/docs/src/capi/tutorial/getting-started.md b/docs/src/capi/tutorial/getting-started.md new file mode 100644 index 000000000..a1ee78d24 --- /dev/null +++ b/docs/src/capi/tutorial/getting-started.md @@ -0,0 +1 @@ +# Install Canonical K8s with Cluster API \ No newline at end of file diff --git a/docs/src/capi/tutorial/index.md b/docs/src/capi/tutorial/index.md new file mode 100644 index 000000000..02352b6dd --- /dev/null +++ b/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 +``` + +```{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. + + +[How-to guides]: ../howto/index +[Explanation section]: ../explanation/index +[Reference section]: ../reference/index diff --git a/docs/src/index.md b/docs/src/index.md index 8334f7ffe..1e1ab1240 100644 --- a/docs/src/index.md +++ b/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/tutorial/index +capi/howto/index +capi/explanation/index +capi/reference/index +``` + --- ````{grid} 1 1 2 2 diff --git a/docs/src/snap/reference/troubleshooting.md b/docs/src/snap/reference/troubleshooting.md index c2a403c7a..daa013331 100644 --- a/docs/src/snap/reference/troubleshooting.md +++ b/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. + [kubeconfig file]: https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/ diff --git a/docs/tools/custom_conf.py b/docs/tools/custom_conf.py index a95974078..53dafffbe 100644 --- a/docs/tools/custom_conf.py +++ b/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. #