Update documentation (#216)

- Mark non-referenced rst files as orphans. These files are part of the starter pack repo and without the `orphan` tag, it causes compile error on RTD) - Use `terminal` block for show the output of a or a series of command(s) - Update section headings following [RST stype guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/)
canonical · Jan 12, 2024 · f8ec12f · f8ec12f
1 parent 41a773b
commit f8ec12f
Show file tree

Hide file tree

Showing 12 changed files with 68 additions and 62 deletions.
diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst
@@ -2,6 +2,8 @@
 Get started
 ===========
 
+This section guides you through steps to prepare the environment and install the application.
+
 Verify Access
 -------------
 To use **COU** you need to have access to a `Charmed OpenStack`_ cloud, which is deployed

diff --git a/docs/help-woke.rst b/docs/help-woke.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================
 Inclusive language check exemptions
 ===================================

diff --git a/docs/how-to/configure-connection.rst b/docs/how-to/configure-connection.rst
@@ -13,8 +13,8 @@ is heavily used.
 * **COU_MODEL_RETRY_BACKOFF** - sets the number of seconds in between connection retry attempts (for example, a backoff of 10 with 3 retries would wait 10s, 20s, and 30s). It’s unit-less and the number represents the number of seconds. Defaults to 2 seconds.
 
 Usage example
-~~~~~~~~~~~~~
+-------------
 
-.. code::
+.. code:: bash
 
-    $  COU_TIMEOUT=120 cou upgrade
+    COU_TIMEOUT=120 cou upgrade
diff --git a/docs/how-to/different-model.rst b/docs/how-to/different-model.rst
@@ -7,24 +7,24 @@ different one, even on a different controller. There are two ways to choose the
 model you want to operate on.
 
 Using CLI argument
-~~~~~~~~~~~~~~~~~~
+------------------
 
-.. code::
+.. code:: bash
 
-    $ cou plan --model <model-name>
-    $ cou plan --model <controller>:<model-name>
+    cou plan --model <model-name>
+    cou plan --model <controller>:<model-name>
 
 Using environment variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 Since **COU** is using `python-libjuju`_, it's possible for some of the environment variables
 mentioned in the documented `Juju environment variables`_ to affect the behaviour of the
 program. For example, `JUJU_DATA`_ can be used to specify a different path for Juju
 configuration files.
 
-.. code::
+.. code:: bash
 
-    $ JUJU_DATA=./my-remote-cloud-juju-data cou plan
+    JUJU_DATA=./my-remote-cloud-juju-data cou plan
 
 
 .. LINKS

diff --git a/docs/how-to/interruption.rst b/docs/how-to/interruption.rst
@@ -14,9 +14,9 @@ the process at any prompt.
 
 Usage example:
 
-.. code:: 
+.. terminal:: 
+    :input: cou upgrade
 
-    $ cou upgrade
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -34,7 +34,6 @@ Usage example:
         Check if the workload of 'keystone' has been upgraded
 
     Would you like to start the upgrade? Continue (y/N): n
-    $
 
 SIGINT or SIGTERM signals
 -------------------------
@@ -50,24 +49,23 @@ the cloud may be left in an inconsistent state.
 
 Exiting before running upgrade plan:
 
-.. code:: 
+.. terminal:: 
+    :input: cou upgrade - # ctrl+c is pressed while connecting to the controller
 
-    $ cou upgrade - # ctrl+c is pressed while connecting to the controller
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connecting to 'default' model... ✖
     charmed-openstack-upgrader has been terminated
-    $ cou upgrade # ctrl+c is pressed while the cloud is being analyzed
+    :input: cou upgrade # ctrl+c is pressed while the cloud is being analyzed
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connecting to 'default' model... ✔
     Analyzing cloud... ✖
     charmed-openstack-upgrader has been terminated
-    $ 
 
 Safe cancel:
 
-.. code::
+.. terminal:: 
+    :input: cou upgrade # ctrl+c is pressed once during the upgrade
 
-    $ cou upgrade # ctrl+c is pressed once during the upgrade
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -76,13 +74,12 @@ Safe cancel:
     Running cloud upgrade...
     Canceling upgrade... (Press ctrl+c again to stop immediately) ✔
     charmed-openstack-upgrader has been stopped safely 
-    $ 
 
 Unsafe cancel:
 
-.. code::
+.. terminal:: 
+    :input: cou upgrade # ctrl+c is pressed twice during the upgrade
 
-    $ cou upgrade # ctrl+c is pressed twice during the upgrade
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -91,4 +88,3 @@ Unsafe cancel:
     Running cloud upgrade...
     Canceling upgrade... (Press ctrl+c again to stop immediately) ✖
     charmed-openstack-upgrader has been terminated without waiting
-    $ 
diff --git a/docs/how-to/no-backup.rst b/docs/how-to/no-backup.rst
@@ -6,13 +6,13 @@ By default, **COU** plans for and runs a backup step of the cloud database befor
 proceeding to actual upgrade steps. This can be turned off with `--no-backup`  flag.
 
 Usage examples
-~~~~~~~~~~~~~~
+--------------
 
 Plan:
 
-.. code:: 
+.. terminal:: 
+    :input: cou plan --no-backup
 
-    $ cou plan --no-backup
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -27,9 +27,9 @@ Plan:
 
 Upgrade:
 
-.. code:: 
+.. terminal:: 
+    :input: cou upgrade --no-backup
 
-    $ cou upgrade --no-backup
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔

diff --git a/docs/how-to/plan-upgrade.rst b/docs/how-to/plan-upgrade.rst
@@ -5,16 +5,16 @@ Plan an upgrade
 The **plan** command is used to generate the upgrade plan; the result will be
 printed on STDOUT.
 
-.. code::
+.. code:: bash
 
-    $ cou plan
+    cou plan
 
 Usage example
-~~~~~~~~~~~~~
+-------------
 
-.. code::
-
-    $ cou plan
+.. terminal:: 
+    :input: cou plan
+
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔

diff --git a/docs/how-to/upgrade-cloud.rst b/docs/how-to/upgrade-cloud.rst
@@ -9,16 +9,16 @@ Use the **upgrade** command to automatically plan and execute the upgrade of you
 cloud. This command runs upgrade in interactive mode by default, requiring the user
 to confirm each step.
 
-.. code::
+.. code:: bash
     
-    $ cou upgrade
+    cou upgrade
 
 Usage example
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
-.. code::
+.. terminal:: 
+    :input: cou upgrade
 
-    $ cou upgrade
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211917.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -117,18 +117,19 @@ Usage example
 Run non-interactive upgrades
 ----------------------------
 
-**COU** provides a non-interactive mode which suppresses user prompts. This option
-allows **COU** to be used by scripts or during upgrade testing. A quiet mode switch
-is also offered, which will only output error logs and a completion message to STDOUT.
+**COU** provides a non-interactive mode which suppresses user prompts and automatically
+continue executing each planned steps. This option allows **COU** to be used by scripts
+or during upgrade testing. A quiet mode switch is also offered, which will only output
+error logs and a completion message to STDOUT.
 
 Usage examples
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 Non-interactive mode:
 
-.. code:: 
+.. terminal:: 
+    :input: cou upgrade --auto-approve
 
-    $ cou upgrade --no-interactive
     Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
     Connected to 'test-model' ✔
     Analyzing cloud... ✔
@@ -145,7 +146,7 @@ Non-interactive mode:
 
 Non-interactive and quiet mode:
 
-.. code:: 
-
-    $ cou upgrade --no-interactive --quiet
+.. terminal:: 
+    :input: cou upgrade --auto-approve --quiet
+
     Upgrade completed.
diff --git a/docs/how-to/verbosity.rst b/docs/how-to/verbosity.rst
@@ -9,28 +9,28 @@ log level.
 The default verbosity level is **error**.
 
 Usage examples
-~~~~~~~~~~~~~~
+--------------
 
 The warning level.
 
-.. code:: 
+.. code:: bash
 
-    $ cou upgrade -v
+    cou upgrade -v
 
 The info level.
 
-.. code:: 
+.. code:: bash
     
-    $ cou upgrade -vv
+    cou upgrade -vv
 
 The debug level for all messages except **python-libjuju** and **websockets**.
 
-.. code:: 
+.. code:: bash
 
-    $ cou upgrade -vvv
+    cou upgrade -vvv
 
 The debug level for all messages including the **python-libjuju** and **websockets**.
 
-.. code:: 
+.. code:: bash
     
-    $ cou upgrade -vvvv
+    cou upgrade -vvvv
diff --git a/docs/readme.rst b/docs/readme.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Documentation starter pack
 ==========================
 

diff --git a/docs/reference/commands.rst b/docs/reference/commands.rst
@@ -11,9 +11,9 @@ The **plan** command will analyse the cloud and output a human-readable represen
 of the proposed upgrade plan. It does not require any interaction. Refer to the
 output below for a description of all allowed options.
 
-.. code::
-    
-    $ cou plan --help
+.. terminal:: 
+    :input: cou plan --help
+
     Usage: cou plan [options]
 
     Show the steps COU will take to upgrade the cloud to the next release.
@@ -35,8 +35,9 @@ Upgrade
 The **upgrade** command will implicitly generate a plan before moving onto the actual
 upgrade phase. Refer to the output below for a description of all available options. 
 
-.. code:: 
-    $ cou upgrade --help
+.. terminal:: 
+    :input: cou upgrade --help
+
     Usage: cou upgrade [options]
 
     Run the cloud upgrade.

diff --git a/docs/setup-script.rst b/docs/setup-script.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Setup script
 ============