docs: add docs for RTD

tmihoc · Dec 12, 2024 · 7772c99 · 7772c99
1 parent e07983e
commit 7772c99
Show file tree

Hide file tree

Showing 455 changed files with 24,448 additions and 919 deletions.
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
@@ -1,3 +1,3 @@
-canonical-sphinx[full] @ git+https://github.com/canonical/canonical-sphinx@main
+canonical-sphinx[full]
 sphinx-autobuild
-sphinxcontrib-svg2pdfconverter[CairoSVG]
+sphinx-tabs
diff --git a/docs/conf.py b/docs/conf.py
@@ -27,7 +27,7 @@
 #
 # TODO: Update with the official name of your project or product
 
-project = "Juju CLI and core"
+project = "Juju"
 author = "Canonical Ltd."
 
 
@@ -103,7 +103,7 @@
 
 html_context = {
     # Product page URL; can be different from product docs URL
-    "product_page": "juju.is",
+     "product_page": "juju.is",
     # Product tag image; the orange part of your logo, shown in the page header
     'product_tag': '/docs/logos/juju-logo.png',
     # Your Discourse instance URL
@@ -201,9 +201,9 @@
 #       - youtube-links
 
 extensions = [
-    "canonical_sphinx",
-    "sphinxcontrib.cairosvgconverter",
-]
+    'canonical_sphinx',
+    'sphinx_design',
+    ]
 
 
 # Excludes files or directories from processing

diff --git a/docs/contributor/explanation/index.md b/docs/contributor/explanation/index.md
@@ -0,0 +1,8 @@
+(explanation)=
+# Explanation
+
+TBA
+
+```{toctree}
+
+```
diff --git a/.../how-to/create-new-mongo-db-collection.md → ...r/howto/create-new-mongo-db-collection.md b/.../how-to/create-new-mongo-db-collection.md → ...r/howto/create-new-mongo-db-collection.md
diff --git a/docs/dev/how-to/create-unit-test-suite.md → ...ntributor/howto/create-unit-test-suite.md b/docs/dev/how-to/create-unit-test-suite.md → ...ntributor/howto/create-unit-test-suite.md
diff --git a/...ow-to/debug-bootstrap-machine-failures.md → ...howto/debug-bootstrap-machine-failures.md b/...ow-to/debug-bootstrap-machine-failures.md → ...howto/debug-bootstrap-machine-failures.md
diff --git a/docs/dev/how-to/index.md → docs/contributor/howto/index.md b/docs/dev/how-to/index.md → docs/contributor/howto/index.md
@@ -1,10 +1,11 @@
-(how-to)=
+(how-to-guides)=
 # How-to guides
+
 How-to guides for Juju developers
 
 ```{toctree}
 :titlesonly:
 :glob:
 
-/dev/how-to/*
-```
+/contributor/howto/*
+```
diff --git a/docs/dev/how-to/merge-forward.md → docs/contributor/howto/merge-forward.md b/docs/dev/how-to/merge-forward.md → docs/contributor/howto/merge-forward.md
diff --git a/docs/dev/how-to/write-a-unit-test.md → docs/contributor/howto/write-a-unit-test.md b/docs/dev/how-to/write-a-unit-test.md → docs/contributor/howto/write-a-unit-test.md
@@ -3,21 +3,9 @@
 
 This document demonstrates how to write a unit test for Juju.
 
-<!-- TOC -->
+## Prepare for the test
 
-* [Prepare for the test](#prepare-for-the-test)
-  * [Create `package_test.go`](#create-package_testgo)
-  * [Create](#create)
-  * [Import `gocheck`](#import-gocheck)
-  * [Add a unit test suite](#add-a-unit-test-suite)
-* [Write the test](#write-the-test)
-* [Run the test](#run-the-test)
-
-<!-- TOC -->
-
-# Prepare for the test
-
-## Create `package_test.go`
+### Create `package_test.go`
 
 [note type=caution]
 This step is necessary only if this file doesn't already exist.
@@ -58,7 +46,7 @@ to run old-style `JujuConnSuite` tests, which test against a running instance of
 These tests are deprecated and are actively being removed. No more should be added.
 [/note]
 
-## Create
+### Create
 
 `
 
@@ -80,7 +68,7 @@ gc "gopkg.in/check.v1"
 `gc` is the usual alias for [gocheck](https://labix.org/gocheck) across all the Juju repositories.
 [/note]
 
-## Add a unit test suite
+### Add a unit test suite
 
 > See also: [Unit test suite](/doc/dev/reference/testing/unit-testing/unit-test-suite.md)
 
@@ -97,7 +85,7 @@ type magicSuite struct{}
 var _ = gc.Suite(&magicSuite{})
 ```
 
-# Write the test
+## Write the test
 
 > See also: [Checker](/doc/dev/reference/testing/unit-testing/checker.md)
 
@@ -131,7 +119,7 @@ c.Assert(res, gc.Equals, 8)
 }
 ```
 
-# Run the test
+## Run the test
 
 Finally, to run the test, do:
 
@@ -153,4 +141,3 @@ See more here [`gocheck` > Selecting which tests to run](https://labix.org/goche
 [/note]
 
 
-> <small>Contributors: @jack-shaw  </small>
diff --git a/docs/dev/how-to/write-an-integration-test.md → ...ibutor/howto/write-an-integration-test.md b/docs/dev/how-to/write-an-integration-test.md → ...ibutor/howto/write-an-integration-test.md
diff --git a/docs/contributor/index.md b/docs/contributor/index.md
@@ -0,0 +1,58 @@
+(dev)=
+# Juju contributor documentation
+
+<!--
+```{toctree}
+:titlesonly:
+:glob:
+:maxdepth: 1
+:hidden:
+
+how-to/index.md
+reference/index.md
+unsorted/index.md
+```
+-->
+
+
+
+````{grid} 1 1 2 2
+
+```{grid-item-card} [Tutorial](tutorial)
+:link: tutorial
+:link-type: doc
+
+**Start here**: a hands-on introduction to Juju for new contributors
+```
+
+```{grid-item-card} [How-to guides](/index)
+:link: howto/index
+:link-type: doc
+
+**Step-by-step guides** covering key operations and common tasks
+```
+
+````
+
+````{grid} 1 1 2 2
+:reverse:
+
+```{grid-item-card} [Reference](/index)
+:link: reference/index
+:link-type: doc
+
+**Technical information** - specifications, APIs, architecture
+```
+
+```{grid-item-card} [Explanation](/index)
+:link: explanation/index
+:link-type: doc
+
+**Discussion and clarification** of key topics
+```
+
+````
+
+
+
+
diff --git a/docs/dev/reference/agent.md → docs/contributor/reference/agent.md b/docs/dev/reference/agent.md → docs/contributor/reference/agent.md
diff --git a/docs/dev/reference/binary-containeragent.md → ...ibutor/reference/binary-containeragent.md b/docs/dev/reference/binary-containeragent.md → ...ibutor/reference/binary-containeragent.md
diff --git a/docs/dev/reference/catacomb-package.md → ...contributor/reference/catacomb-package.md b/docs/dev/reference/catacomb-package.md → ...contributor/reference/catacomb-package.md
diff --git a/docs/dev/reference/cve.md → docs/contributor/reference/cve.md b/docs/dev/reference/cve.md → docs/contributor/reference/cve.md
diff --git a/docs/dev/reference/dependency-package.md → ...ntributor/reference/dependency-package.md b/docs/dev/reference/dependency-package.md → ...ntributor/reference/dependency-package.md
diff --git a/docs/dev/reference/index.md → docs/contributor/reference/index.md b/docs/dev/reference/index.md → docs/contributor/reference/index.md
diff --git a/docs/dev/reference/testing/index.md → docs/contributor/reference/testing/index.md b/docs/dev/reference/testing/index.md → docs/contributor/reference/testing/index.md
diff --git a/...ence/testing/integration-testing/index.md → ...ence/testing/integration-testing/index.md b/...ence/testing/integration-testing/index.md → ...ence/testing/integration-testing/index.md
diff --git a/...gration-testing/integration-test-suite.md → ...gration-testing/integration-test-suite.md b/...gration-testing/integration-test-suite.md → ...gration-testing/integration-test-suite.md
diff --git a/...ting/integration-testing/test-includes.md → ...ting/integration-testing/test-includes.md b/...ting/integration-testing/test-includes.md → ...ting/integration-testing/test-includes.md
diff --git a/...reference/testing/unit-testing/checker.md → ...reference/testing/unit-testing/checker.md b/...reference/testing/unit-testing/checker.md → ...reference/testing/unit-testing/checker.md
diff --git a/...v/reference/testing/unit-testing/index.md → ...r/reference/testing/unit-testing/index.md b/...v/reference/testing/unit-testing/index.md → ...r/reference/testing/unit-testing/index.md
diff --git a/...e/testing/unit-testing/unit-test-suite.md → ...e/testing/unit-testing/unit-test-suite.md b/...e/testing/unit-testing/unit-test-suite.md → ...e/testing/unit-testing/unit-test-suite.md
diff --git a/...erence/testing/unit-testing/util-suite.md → ...erence/testing/unit-testing/util-suite.md b/...erence/testing/unit-testing/util-suite.md → ...erence/testing/unit-testing/util-suite.md
diff --git a/docs/dev/reference/tomb-package.md → docs/contributor/reference/tomb-package.md b/docs/dev/reference/tomb-package.md → docs/contributor/reference/tomb-package.md
diff --git a/docs/dev/reference/worker-interface.md → ...contributor/reference/worker-interface.md b/docs/dev/reference/worker-interface.md → ...contributor/reference/worker-interface.md
diff --git a/docs/dev/reference/worker-package.md → docs/contributor/reference/worker-package.md b/docs/dev/reference/worker-package.md → docs/contributor/reference/worker-package.md
diff --git a/docs/dev/reference/worker.md → docs/contributor/reference/worker.md b/docs/dev/reference/worker.md → docs/contributor/reference/worker.md
diff --git a/docs/dev/tutorial.md → docs/contributor/tutorial.md b/docs/dev/tutorial.md → docs/contributor/tutorial.md
diff --git a/docs/dev/unsorted/Debugging-Races.md → docs/contributor/unsorted/Debugging-Races.md b/docs/dev/unsorted/Debugging-Races.md → docs/contributor/unsorted/Debugging-Races.md
diff --git a/...nsorted/Diagnosing-MongoDB-Performance.md → ...nsorted/Diagnosing-MongoDB-Performance.md b/...nsorted/Diagnosing-MongoDB-Performance.md → ...nsorted/Diagnosing-MongoDB-Performance.md
diff --git a/docs/dev/unsorted/FAQ.md → docs/contributor/unsorted/FAQ.md b/docs/dev/unsorted/FAQ.md → docs/contributor/unsorted/FAQ.md
diff --git a/...nsorted/Guidelines-for-writing-workers.md → ...nsorted/Guidelines-for-writing-workers.md b/...nsorted/Guidelines-for-writing-workers.md → ...nsorted/Guidelines-for-writing-workers.md
diff --git a/docs/dev/unsorted/api.md → docs/contributor/unsorted/api.md b/docs/dev/unsorted/api.md → docs/contributor/unsorted/api.md
diff --git a/docs/dev/unsorted/architectural-overview.md → ...ibutor/unsorted/architectural-overview.md b/docs/dev/unsorted/architectural-overview.md → ...ibutor/unsorted/architectural-overview.md
diff --git a/docs/dev/unsorted/bootstrapping.md → docs/contributor/unsorted/bootstrapping.md b/docs/dev/unsorted/bootstrapping.md → docs/contributor/unsorted/bootstrapping.md
diff --git a/docs/dev/unsorted/code-review-checklists.md → ...ibutor/unsorted/code-review-checklists.md b/docs/dev/unsorted/code-review-checklists.md → ...ibutor/unsorted/code-review-checklists.md
diff --git a/docs/dev/unsorted/conventional-commits.md → ...tributor/unsorted/conventional-commits.md b/docs/dev/unsorted/conventional-commits.md → ...tributor/unsorted/conventional-commits.md
diff --git a/...ev/unsorted/cross-platform-development.md → ...or/unsorted/cross-platform-development.md b/...ev/unsorted/cross-platform-development.md → ...or/unsorted/cross-platform-development.md
diff --git a/docs/dev/unsorted/death-and-destruction.md → ...ributor/unsorted/death-and-destruction.md b/docs/dev/unsorted/death-and-destruction.md → ...ributor/unsorted/death-and-destruction.md
diff --git a/docs/dev/unsorted/entity-creation.md → docs/contributor/unsorted/entity-creation.md b/docs/dev/unsorted/entity-creation.md → docs/contributor/unsorted/entity-creation.md
diff --git a/docs/dev/unsorted/facades.md → docs/contributor/unsorted/facades.md b/docs/dev/unsorted/facades.md → docs/contributor/unsorted/facades.md
diff --git a/docs/dev/unsorted/fixing-bugs.md → docs/contributor/unsorted/fixing-bugs.md b/docs/dev/unsorted/fixing-bugs.md → docs/contributor/unsorted/fixing-bugs.md
diff --git a/docs/dev/unsorted/high_availability.md → ...contributor/unsorted/high_availability.md b/docs/dev/unsorted/high_availability.md → ...contributor/unsorted/high_availability.md
diff --git a/docs/dev/unsorted/how-to-write-tests.md → ...ontributor/unsorted/how-to-write-tests.md b/docs/dev/unsorted/how-to-write-tests.md → ...ontributor/unsorted/how-to-write-tests.md
diff --git a/...wto-implement-effective-config-structs.md → ...wto-implement-effective-config-structs.md b/...wto-implement-effective-config-structs.md → ...wto-implement-effective-config-structs.md
diff --git a/...ted/implementing-environment-providers.md → ...ted/implementing-environment-providers.md b/...ted/implementing-environment-providers.md → ...ted/implementing-environment-providers.md
diff --git a/docs/dev/unsorted/index.md → docs/contributor/unsorted/index.md b/docs/dev/unsorted/index.md → docs/contributor/unsorted/index.md
diff --git a/docs/dev/unsorted/interactive-Commands.md → ...tributor/unsorted/interactive-Commands.md b/docs/dev/unsorted/interactive-Commands.md → ...tributor/unsorted/interactive-Commands.md
diff --git a/...unsorted/juju-api-design-specification.md → ...unsorted/juju-api-design-specification.md b/...unsorted/juju-api-design-specification.md → ...unsorted/juju-api-design-specification.md
diff --git a/...unsorted/juju-api-implementation-guide.md → ...unsorted/juju-api-implementation-guide.md b/...unsorted/juju-api-implementation-guide.md → ...unsorted/juju-api-implementation-guide.md
diff --git a/docs/dev/unsorted/lifecycles.md → docs/contributor/unsorted/lifecycles.md b/docs/dev/unsorted/lifecycles.md → docs/contributor/unsorted/lifecycles.md
diff --git a/...v/unsorted/logging-in-to-the-apiserver.md → ...r/unsorted/logging-in-to-the-apiserver.md b/...v/unsorted/logging-in-to-the-apiserver.md → ...r/unsorted/logging-in-to-the-apiserver.md
diff --git a/docs/dev/unsorted/loginflow.md → docs/contributor/unsorted/loginflow.md b/docs/dev/unsorted/loginflow.md → docs/contributor/unsorted/loginflow.md
diff --git a/docs/dev/unsorted/managing-complexity.md → ...ntributor/unsorted/managing-complexity.md b/docs/dev/unsorted/managing-complexity.md → ...ntributor/unsorted/managing-complexity.md
diff --git a/docs/dev/unsorted/mgo-txn-example.md → docs/contributor/unsorted/mgo-txn-example.md b/docs/dev/unsorted/mgo-txn-example.md → docs/contributor/unsorted/mgo-txn-example.md
diff --git a/docs/dev/unsorted/provisioning.md → docs/contributor/unsorted/provisioning.md b/docs/dev/unsorted/provisioning.md → docs/contributor/unsorted/provisioning.md
diff --git a/.../dev/unsorted/read-before-contributing.md → ...utor/unsorted/read-before-contributing.md b/.../dev/unsorted/read-before-contributing.md → ...utor/unsorted/read-before-contributing.md
diff --git a/docs/dev/unsorted/review-checklist.md → .../contributor/unsorted/review-checklist.md b/docs/dev/unsorted/review-checklist.md → .../contributor/unsorted/review-checklist.md
diff --git a/docs/dev/unsorted/simplestreams-metadata.md → ...ibutor/unsorted/simplestreams-metadata.md b/docs/dev/unsorted/simplestreams-metadata.md → ...ibutor/unsorted/simplestreams-metadata.md
diff --git a/docs/dev/unsorted/storage-model.uml → docs/contributor/unsorted/storage-model.uml b/docs/dev/unsorted/storage-model.uml → docs/contributor/unsorted/storage-model.uml
diff --git a/docs/dev/unsorted/style-guide.md → docs/contributor/unsorted/style-guide.md b/docs/dev/unsorted/style-guide.md → docs/contributor/unsorted/style-guide.md
diff --git a/docs/dev/unsorted/system-ssh-key.md → docs/contributor/unsorted/system-ssh-key.md b/docs/dev/unsorted/system-ssh-key.md → docs/contributor/unsorted/system-ssh-key.md
diff --git a/docs/dev/unsorted/third-party-go-clients.md → ...ibutor/unsorted/third-party-go-clients.md b/docs/dev/unsorted/third-party-go-clients.md → ...ibutor/unsorted/third-party-go-clients.md
diff --git a/docs/custom_conf.py b/docs/custom_conf.py
@@ -2,7 +2,7 @@
 import subprocess
 import shutil
 
-cli_dir = "user/cli/"
+cli_dir = "user/reference/juju-cli/list-of-juju-cli-commands/"
 
 # Remove existing cli folder to regenerate it
 if os.path.exists(cli_dir):
@@ -12,29 +12,20 @@
 subprocess.run(["juju", 'documentation', '--split', '--no-index', '--out', cli_dir],
                    check=True)
 
-titles = []
-
 for page in os.listdir(cli_dir):
-    title = page[:-3]
+    title = "`juju " + page[:-3]+ "`"
+    anchor = "command-juju-" + page[:-3]
     # Add sphinx names to each file.
     with open(os.path.join(cli_dir, page), 'r+') as mdfile:
         content = mdfile.read()
         # Remove trailing seperated (e.g. ----)
         content = content.rstrip(" -\n")
         mdfile.seek(0, 0)
-        mdfile.write('(' + page + ')=\n' + 
-                     '# `' + title + '`\n' + 
+        mdfile.write('(' + anchor + ')=\n' +
+                     '# ' + title + '\n' +
                      content)
-    titles.append(title)
-
+
 
 # Add the template for the index file containing the command list.
 if (not os.path.isfile(cli_dir + 'index.md')):
-    os.system('cp ' + 'user/cli_index.template ' + cli_dir + 'index.md')
-
-# Write the list of commands to the index file toctree.
-with open(cli_dir + "index.md", 'a') as index:
-    titles.sort()
-    for title in titles:
-        index.write(title + '\n')
-    index.write("```")
+    os.system('cp ' + 'user/reference/juju-cli/cli_index.template ' + cli_dir + 'index.md')
diff --git a/docs/dev/index.md b/docs/dev/index.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,30 +1,77 @@
-# Juju CLI and Controller documentation
+# Juju documentation
+
+Juju is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure, using special software operators called ‘charms’.
+
+Juju provides a model-driven way to install, provision, maintain, update, upgrade, and integrate applications on and across Kubernetes containers, Linux containers, virtual machines, and bare metal machines, on public or private cloud.
+
+As such, Juju makes it simple, intuitive, and efficient to manage the full lifecycle of complex applications in hybrid cloud.
+
+For system operators and DevOps who manage applications in the cloud, Juju simplifies code; for CIOs, it helps align code with business decisions.
 
-This documentation contains the CIL and controller documentation.
 
 ## In this documentation
 
 ```{toctree}
 :titlesonly:
-:glob:
 :hidden:
 
-dev/index.md
 user/index.md
+- Tutorial <user/tutorial>
+- How-to guides <user/howto/index>
+- Reference <user/reference/index>
+- Explanation <user/explanation/index>
+contributor/index.md
+- Tutorial <contributor/tutorial>
+- How-to guides <contributor/howto/index>
+- Reference <contributor/reference/index>
+- Explanation <contributor/explanation/index>
+- Unsorted <contributor/unsorted/index>
 ````
 
 ````{grid} 1 1 2 2 
 
-```{grid-item-card} [User reference](user/index.md)
+```{grid-item-card} [User docs](user/index.md)
+
+Docs for people who want to use `juju`, whether as SREs or as charm authors
 
-**Reference inforamtion** for the controller and CLI
+- [Tutorial](user/tutorial) -> **Start here!**
+- [How-to guides](user/howto/index)
+- [Reference](user/reference/index)
+- [Explanation](user/explanation/index)
 
 ```
 
-```{grid-item-card} [Developer documentation](dev/index.md)
+```{grid-item-card} [Contributor docs](contributor/index.md)
+
+Docs for people who want to contribute to `juju`, whether docs or code
 
-**Developer information** for understanding and working on Juju
+- [Tutorial](contributor/tutorial)
+- [How-to guides](contributor/howto/index)
+- [Reference](contributor/reference/index)
+- [Explanation](contributor/explanation/index)
+- [Unsorted](contributor/unsorted/index)
 
 ```
 
 ````
+
+(project-and-community)=
+## Project and community
+
+Juju is an open source project that warmly welcomes community projects, contributions, suggestions, fixes and
+constructive feedback.
+
+* Learn about the [Roadmap & Releases](https://discourse.charmhub.io/t/5064)
+* Read our [Code of Conduct ](https://ubuntu.com/community/code-of-conduct)
+* Join our [Matrix chat](https://matrix.to/#/#charmhub-jujudev:ubuntu.com)
+* Join the [Discourse forum ](https://discourse.charmhub.io/t/welcome-to-the-charmed-operator-community/8) to talk
+  about [Juju](https://discourse.charmhub.io/tags/c/juju/6/community-workshop), [charms](https://discourse.charmhub.io/c/charm/41), [docs](https://discourse.charmhub.io/c/doc/22),
+  or [to meet the community](https://discourse.charmhub.io/tag/community-workshop)
+* Report a bug on [Launchpad ](https://bugs.launchpad.net/juju) (for code)
+  or [GitHub](https://github.com/juju/docs/issues) (for docs)
+* Contribute to the documentation
+  on [Discourse](https://discourse.charmhub.io/t/documentation-guidelines-for-contributors/1245)
+* Contribute to the code on [GitHub](https://github.com/juju/juju/blob/develop/CONTRIBUTING.md)
+* Visit the [Juju careers page](https://juju.is/careers)
+
+