Merge branch 'main' into data-plane-pre-check

.github/workflows/automatic-doc-checks.yml

@@ -0,0 +1,16 @@
+name: Main Documentation Checks
+
+on:
+  - push
+  - pull_request
+  - workflow_dispatch
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true  
+
+jobs:
+  documentation-checks:
+    uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
+    with:
+      working-directory: 'docs'

.wokeignore

@@ -0,0 +1 @@
+docs/.wokeignore

README.md

@@ -1,25 +1,41 @@
-# DISCLAIMER
+# Charmed OpenStack Upgrader
 
-This is a work in progress prototype. The code contained in this repository
-may not be representative of what the final approach should be.
-It is likely that the end result will live under a different name, in a
-different repository, and only use some of the code and ideas found here.
+Charmed OpenStack Upgrader (COU) is an application (packaged as a snap) to upgrade
+a Canonical distribution of [Charmed OpenStack](https://ubuntu.com/openstack/docs/overview)
+in an automated and frictionless manner. The application detects the version of the
+running cloud and proposes an upgrade plan to the next available OpenStack release.
+
+For more information, please refer to [COU Documentation](https://canonical-charmed-openstack-upgrader.readthedocs-hosted.com/).
 
 # Setup
 
+The Charmed OpenStack Upgrader snap can be installed directly from the snap store:
+
 ```bash
-# Instructions for local builds until we have automatic connections and alias
-make clean
-sudo snap remove charmed-openstack-upgrader --purge
-make build
-sudo snap install ./charmed-openstack-upgrader.snap --dangerous
-sudo snap connect charmed-openstack-upgrader:juju-client-observe snapd
-sudo snap connect charmed-openstack-upgrader:dot-local-share-cou snapd
-sudo snap connect charmed-openstack-upgrader:ssh-public-keys snapd
-sudo snap alias charmed-openstack-upgrader.cou cou
+sudo snap install charmed-openstack-upgrader
 ```
 
-Then you can use ```cou```
+An alias `cou` will be automatically enabled upon successful installation.
+
+Run `cou -h` to learn about the available commands: 
+
+```bash
+Usage: cou [options] <command>
+
+Charmed OpenStack Upgrader (cou) is an application to upgrade
+a Canonical distribution of Charmed OpenStack.
+The application auto-detects the version of the running cloud
+and will propose an upgrade to the next available version.
+
+Options:
+  -h, --help           Show this help message and exit.
+  --version, -V        Show version details.
+
+Commands:
+  {help,plan,upgrade}  For more information about a command, run 'cou help <command>'.
+    plan               Show the steps COU will take to upgrade the cloud to the next release.
+    upgrade            Run the cloud upgrade.
+```
 
 ## Environment Variables
 
@@ -38,3 +54,7 @@ Application supports:
 - Focal/Wallaby -> Focal/Yoga
 
 upgrades.
+
+# License
+Charmed OpenStack Upgrader is a free software, distributed under the Apache-2.0 license. Refer to the
+[LICENSE](https://github.com/canonical/snap-tempest/blob/main/LICENSE) file for details.

docs/.custom_wordlist.txt

@@ -0,0 +1,23 @@
+OpenStack
+Upgrader
+ussuri
+Github
+frictionless
+COU
+cou
+COUModel
+SIGINT
+SIGINTs
+SIGTERM
+SIGTERMs
+STDOUT
+juju
+libjuju
+VPN
+ctrl
+snapcraft
+OpenStackApplication
+yaml
+backoff
+BACKOFF
+websockets

docs/.gitignore

@@ -0,0 +1,11 @@
+/*env*/
+.sphinx/venv/
+.sphinx/warnings.txt
+.sphinx/.wordlist.dic
+.sphinx/.doctrees/
+.sphinx/node_modules/
+package*.json
+_build
+.DS_Store
+__pycache__
+.idea/

docs/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/.sphinx/requirements.txt

docs/.sphinx/_static/custom.css

@@ -0,0 +1,210 @@
+/** Fix the font weight (300 for normal, 400 for slightly bold) **/
+
+div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
+    font-weight: 300
+}
+
+.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
+    font-weight: 400;
+}
+
+/** Table styling **/
+
+th.head {
+    text-transform: uppercase;
+    font-size: var(--font-size--small);
+}
+
+table.docutils {
+    border: 0;
+    box-shadow: none;
+    width:100%;
+}
+
+table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
+    border-right: none;
+    border-left: none;
+}
+
+/* Allow to centre text horizontally in table data cells */
+table.align-center {
+    text-align: center !important;
+}
+
+/** No rounded corners **/
+
+.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
+    border-radius: 0;
+}
+
+/** Admonition styling **/
+
+.admonition {
+    border-top: 1px solid #d9d9d9;
+    border-right: 1px solid #d9d9d9;
+    border-bottom: 1px solid #d9d9d9;
+}
+
+/** Color for the "copy link" symbol next to headings **/
+
+a.headerlink {
+    color: var(--color-brand-primary);
+}
+
+/** Line to the left of the current navigation entry **/
+
+.sidebar-tree li.current-page {
+    border-left: 2px solid var(--color-brand-primary);
+}
+
+/** Some tweaks for issue #16 **/
+
+[role="tablist"] {
+    border-bottom: 1px solid var(--color-sidebar-item-background--hover);
+}
+
+.sphinx-tabs-tab[aria-selected="true"] {
+    border: 0;
+    border-bottom: 2px solid var(--color-brand-primary);
+    background-color: var(--color-sidebar-item-background--current);
+    font-weight:300;
+}
+
+.sphinx-tabs-tab{
+    color: var(--color-brand-primary);
+    font-weight:300;
+}
+
+.sphinx-tabs-panel {
+    border: 0;
+    border-bottom: 1px solid var(--color-sidebar-item-background--hover);
+    background: var(--color-background-primary);
+}
+
+button.sphinx-tabs-tab:hover {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+/** Custom classes to fix scrolling in tables by decreasing the
+    font size or breaking certain columns.
+    Specify the classes in the Markdown file with, for example:
+    ```{rst-class} break-col-4 min-width-4-8
+    ```
+**/
+
+table.dec-font-size {
+    font-size: smaller;
+}
+table.break-col-1 td.text-left:first-child {
+    word-break: break-word;
+}
+table.break-col-4 td.text-left:nth-child(4) {
+    word-break: break-word;
+}
+table.min-width-1-15 td.text-left:first-child {
+    min-width: 15em;
+}
+table.min-width-4-8 td.text-left:nth-child(4) {
+    min-width: 8em;
+}
+
+/** Underline for abbreviations **/
+
+abbr[title] {
+    text-decoration: underline solid #cdcdcd;
+}
+
+/** Use the same style for right-details as for left-details **/
+.bottom-of-page .right-details {
+    font-size: var(--font-size--small);
+    display: block;
+}
+
+/** Version switcher */
+button.version_select {
+  color: var(--color-foreground-primary);
+  background-color: var(--color-toc-background);
+  padding: 5px 10px;
+  border: none;
+}
+
+.version_select:hover, .version_select:focus {
+    background-color: var(--color-sidebar-item-background--hover);
+}
+
+.version_dropdown {
+  position: relative;
+  display: inline-block;
+  text-align: right;
+  font-size: var(--sidebar-item-font-size);
+}
+
+.available_versions {
+  display: none;
+  position: absolute;
+  right: 0px;
+  background-color: var(--color-toc-background);
+  box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
+  z-index: 11;
+}
+
+.available_versions a {
+  color: var(--color-foreground-primary);
+  padding: 12px 16px;
+  text-decoration: none;
+  display: block;
+}
+
+.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
+
+.show {display:block;}
+
+/** Fix for nested numbered list - the nested list is lettered **/
+ol.arabic ol.arabic {
+  list-style: lower-alpha;
+}
+
+/** Make expandable sections look like links **/
+details summary {
+    color: var(--color-link);
+}
+
+/** Fix the styling of the version box for readthedocs **/
+
+#furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version  {
+    background: var(--color-sidebar-item-background--hover);
+}
+
+.rst-versions .rst-other-versions dd a {
+    color: var(--color-link);
+}
+
+#furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
+    color: var(--color-sidebar-link-text);
+}
+
+.rst-versions .rst-current-version {
+    color: var(--color-version-popup);
+    font-weight: bolder;
+}
+
+/* Code-block copybutton invisible by default
+   (overriding Furo config to achieve default copybutton setting). */
+.highlight button.copybtn {
+   opacity: 0;
+}
+
+/* Mimicking the 'Give feedback' button for UX consistency */
+.sidebar-search-container input[type=submit] {
+    color: #FFFFFF;
+    border: 2px solid #D6410D;
+    padding: var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal);
+    background: #D6410D;
+    font-weight: bold;
+    font-size: var(--font-size--small);
+    cursor: pointer;
+}
+
+.sidebar-search-container input[type=submit]:hover {
+    text-decoration: underline;
+}