diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst index 42fbed62..1f5d2a96 100644 --- 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 index 8bc2a488..7ee332d3 100644 --- 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 index db8e7aad..42524625 100644 --- 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 \ No newline at end of file + COU_TIMEOUT=120 cou upgrade \ No newline at end of file diff --git a/docs/how-to/different-model.rst b/docs/how-to/different-model.rst index 6321a729..ac05386f 100644 --- 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 - $ cou plan --model : + cou plan --model + cou plan --model : 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 index d453f70b..99a92997 100644 --- 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 - $ \ No newline at end of file diff --git a/docs/how-to/no-backup.rst b/docs/how-to/no-backup.rst index 64a806fe..e7b67a28 100644 --- 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 index 4e541f23..1b59261f 100644 --- 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 index 733fcfe9..1d52e4a3 100644 --- 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. \ No newline at end of file diff --git a/docs/how-to/verbosity.rst b/docs/how-to/verbosity.rst index de0fda37..d8d3bd6a 100644 --- 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 \ No newline at end of file + cou upgrade -vvvv \ No newline at end of file diff --git a/docs/readme.rst b/docs/readme.rst index 5957c891..8587ee19 100644 --- 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 index 9f7c22cd..5e8308fa 100644 --- 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 index f0e471fe..ee10c4ab 100644 --- a/docs/setup-script.rst +++ b/docs/setup-script.rst @@ -1,3 +1,5 @@ +:orphan: + Setup script ============