cloud-init-dev team mailing list archive

[Scott Moser <ssmoser2+ubuntu@xxxxxxxxx>]

Scott Moser has proposed merging ~smoser/cloud-init:cleanup/no-warnings-in-doc into cloud-init:master.

Commit message:
doc: fix all warnings issued by 'tox -e doc'

Building doc would issue some warnings.  This fixes all the warnings,
and changes the "code blocks" that were listed as 'bash' to instead
be 'shell-session'.

Requested reviews:
  cloud-init commiters (cloud-init-dev)

For more details, see:
https://code.launchpad.net/~smoser/cloud-init/+git/cloud-init/+merge/341420

see commit message
-- 
Your team cloud-init commiters is requested to review the proposed merge of ~smoser/cloud-init:cleanup/no-warnings-in-doc into cloud-init:master.

diff --git a/cloudinit/config/cc_runcmd.py b/cloudinit/config/cc_runcmd.py
index 449872f..539cbd5 100644
--- a/cloudinit/config/cc_runcmd.py
+++ b/cloudinit/config/cc_runcmd.py
@@ -39,8 +39,10 @@ schema = {
         using ``sh``.
 
         .. note::
-        all commands must be proper yaml, so you have to quote any characters
-        yaml would eat (':' can be problematic)"""),
+
+          all commands must be proper yaml, so you have to quote any characters
+          yaml would eat (':' can be problematic)
+    """),
     'distros': distros,
     'examples': [dedent("""\
         runcmd:
diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst
index ae3a0c7..3e2c9e3 100644
--- a/doc/rtd/topics/capabilities.rst
+++ b/doc/rtd/topics/capabilities.rst
@@ -44,13 +44,14 @@ Currently defined feature names include:
 CLI Interface
 =============
 
-   The command line documentation is accessible on any cloud-init
-installed system:
+The command line documentation is accessible on any cloud-init installed
+system:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   % cloud-init --help
   usage: cloud-init [-h] [--version] [--file FILES]
+
                     [--debug] [--force]
                     {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
                     ...
@@ -88,7 +89,7 @@ Print out each feature supported.  If cloud-init does not have the
 features subcommand, it also does not support any features described in
 this document.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   % cloud-init features
   NETWORK_CONFIG_V1
@@ -100,10 +101,11 @@ cloud-init status
 -----------------
 Report whether cloud-init is running, done, disabled or errored. Exits
 non-zero if an error is detected in cloud-init.
+
  * **--long**: Detailed status information.
  * **--wait**: Block until cloud-init completes.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   % cloud-init status --long
   status: done
@@ -214,7 +216,7 @@ of once-per-instance:
  * **--frequency**: Optionally override the declared module frequency
    with one of (always|once-per-instance|once)
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   % cloud-init single --name set_hostname --frequency always
 
diff --git a/doc/rtd/topics/debugging.rst b/doc/rtd/topics/debugging.rst
index c2b47ed..3a00af1 100644
--- a/doc/rtd/topics/debugging.rst
+++ b/doc/rtd/topics/debugging.rst
@@ -1,6 +1,6 @@
-**********************
+********************************
 Testing and debugging cloud-init
-**********************
+********************************
 
 Overview
 ========
@@ -10,7 +10,7 @@ deployed instances.
 .. _boot_time_analysis:
 
 Boot Time Analysis - cloud-init analyze
-======================================
+=======================================
 Occasionally instances don't appear as performant as we would like and
 cloud-init packages a simple facility to inspect what operations took
 cloud-init the longest during boot and setup.
@@ -22,9 +22,9 @@ determine the long-pole in cloud-init configuration and setup. These
 subcommands default to reading /var/log/cloud-init.log.
 
 * ``analyze show`` Parse and organize cloud-init.log events by stage and
-include each sub-stage granularity with time delta reports.
+  include each sub-stage granularity with time delta reports.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ cloud-init analyze show -i my-cloud-init.log
     -- Boot Record 01 --
@@ -41,9 +41,9 @@ include each sub-stage granularity with time delta reports.
 
 
 * ``analyze dump`` Parse cloud-init.log into event records and return a list of
-dictionaries that can be consumed for other reporting needs.
+  dictionaries that can be consumed for other reporting needs.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ cloud-init analyze blame -i my-cloud-init.log
     [
@@ -56,10 +56,10 @@ dictionaries that can be consumed for other reporting needs.
      },...
 
 * ``analyze blame`` Parse cloud-init.log into event records and sort them based
-on highest time cost for quick assessment of areas of cloud-init that may need
-improvement.
+  on highest time cost for quick assessment of areas of cloud-init that may
+  need improvement.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ cloud-init analyze blame -i my-cloud-init.log
     -- Boot Record 11 --
@@ -73,7 +73,7 @@ Analyze quickstart - LXC
 ---------------------------
 To quickly obtain a cloud-init log try using lxc on any ubuntu system:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   $ lxc init ubuntu-daily:xenial x1
   $ lxc start x1
@@ -87,17 +87,21 @@ Analyze quickstart - KVM
 To quickly analyze a KVM a cloud-init log:
 
 1. Download the current cloud image
-  wget https://cloud-images.ubuntu.com/daily/server/xenial/current/xenial-server-cloudimg-amd64.img
+
+.. code-block:: shell-session
+
+    $ wget https://cloud-images.ubuntu.com/daily/server/xenial/current/xenial-server-cloudimg-amd64.img
+
 2. Create a snapshot image to preserve the original cloud-image
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ qemu-img create -b xenial-server-cloudimg-amd64.img -f qcow2 \
     test-cloudinit.qcow2
 
 3. Create a seed image with metadata using `cloud-localds`
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ cat > user-data <<EOF
       #cloud-config
@@ -108,7 +112,7 @@ To quickly analyze a KVM a cloud-init log:
 
 4. Launch your modified VM
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $  kvm -m 512 -net nic -net user -redir tcp:2222::22 \
    -drive file=test-cloudinit.qcow2,if=virtio,format=qcow2 \
@@ -116,7 +120,7 @@ To quickly analyze a KVM a cloud-init log:
 
 5. Analyze the boot (blame, dump, show)
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ ssh -p 2222 ubuntu@localhost 'cat /var/log/cloud-init.log' | \
    cloud-init analyze blame -i -
@@ -136,7 +140,7 @@ prevents a module from running again if it has already been run. To ensure that
 a module is run again, the desired frequency can be overridden on the
 commandline:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   $ sudo cloud-init single --name cc_ssh --frequency always
   ...
diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst
index 96c1cf5..1e99455 100644
--- a/doc/rtd/topics/network-config.rst
+++ b/doc/rtd/topics/network-config.rst
@@ -202,7 +202,7 @@ is helpful for examining expected output for a given input format.
 
 CLI Interface :
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   % tools/net-convert.py --help
   usage: net-convert.py [-h] --network-data PATH --kind
@@ -222,7 +222,7 @@ CLI Interface :
 
 Example output converting V2 to sysconfig:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
   % tools/net-convert.py --network-data v2.yaml --kind yaml \
       --output-kind sysconfig -d target
diff --git a/doc/rtd/topics/tests.rst b/doc/rtd/topics/tests.rst
index bf04bb3..cac4a6e 100644
--- a/doc/rtd/topics/tests.rst
+++ b/doc/rtd/topics/tests.rst
@@ -21,7 +21,7 @@ Overview
 In order to avoid the need for dependencies and ease the setup and
 configuration users can run the integration tests via tox:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ git clone https://git.launchpad.net/cloud-init
     $ cd cloud-init
@@ -51,7 +51,7 @@ The first example will provide a complete end-to-end run of data
 collection and verification. There are additional examples below
 explaining how to run one or the other independently.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ git clone https://git.launchpad.net/cloud-init
     $ cd cloud-init
@@ -93,7 +93,7 @@ If developing tests it may be necessary to see if cloud-config works as
 expected and the correct files are pulled down. In this case only a
 collect can be ran by running:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ tox -e citest -- collect -n xenial --data-dir /tmp/collection
 
@@ -106,7 +106,7 @@ Verify
 When developing tests it is much easier to simply rerun the verify scripts
 without the more lengthy collect process. This can be done by running:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ tox -e citest -- verify --data-dir /tmp/collection
 
@@ -133,7 +133,7 @@ cloud-init deb from or use the ``tree_run`` command using a copy of
 cloud-init located in a different directory, use the option ``--cloud-init
 /path/to/cloud-init``.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ tox -e citest -- tree_run --verbose \
         --os-name xenial --os-name stretch \
@@ -331,7 +331,7 @@ Integration tests are located under the `tests/cloud_tests` directory.
 Test configurations are placed under `configs` and the test verification
 scripts under `testcases`:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     cloud-init$ tree -d tests/cloud_tests/
     tests/cloud_tests/
@@ -362,7 +362,7 @@ The following would create a test case named ``example`` under the
 ``modules`` category with the given description, and cloud config data read
 in from ``/tmp/user_data``.
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ tox -e citest -- create modules/example \
         -d "a simple example test case" -c "$(< /tmp/user_data)"
@@ -385,7 +385,7 @@ Development Checklist
     * Placed in the appropriate sub-folder in the test cases directory
 * Tested by running the test:
 
-   .. code-block:: bash
+   .. code-block:: shell-session
 
        $ tox -e citest -- run -verbose \
            --os-name <release target> \
@@ -404,14 +404,14 @@ These configuration files are the standard that the AWS cli and other AWS
 tools utilize for interacting directly with AWS itself and are normally
 generated when running ``aws configure``:
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ cat $HOME/.aws/credentials
     [default]
     aws_access_key_id = <KEY HERE>
     aws_secret_access_key = <KEY HERE>
 
-.. code-block:: bash
+.. code-block:: shell-session
 
     $ cat $HOME/.aws/config
     [default]