canonical · TheRealFalcon · Mar 29, 2022 · Mar 11, 2022 · Mar 11, 2022 · Mar 11, 2022
diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -1,10 +1,10 @@
 doc8
-m2r
-sphinx<2
-sphinx_rtd_theme
+m2r2
+sphinx==4.3.0
+sphinx_rtd_theme==1.0.0
 pyyaml
+sphinx-panels
 
 # Indirect dependencies
 jinja2<3.1.0  # https://github.com/readthedocs/readthedocs.org/issues/9037
-docutils<0.18
-mistune<2.0.0  # https://github.com/miyakogi/m2r/issues/66
+docutils==0.16  # https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
diff --git a/doc/examples/cloud-config-user-groups.txt b/doc/examples/cloud-config-user-groups.txt
@@ -64,7 +64,7 @@ users:
 #   lock_passwd: Defaults to true. Lock the password to disable password login
 #   inactive: Number of days after password expires until account is disabled
 #   passwd: The hash -- not the password itself -- of the password you want
-#           to use for this user. You can generate a safe hash via:
+#           to use for this user. You can generate a hash via:
 #               mkpasswd --method=SHA-512 --rounds=4096
 #           (the above command would create from stdin an SHA-512 password hash
 #           with 4096 salt rounds)
@@ -81,9 +81,8 @@ users:
 #               In other words, this feature is a potential security risk and is
 #               provided for your convenience only. If you do not fully trust the
 #               medium over which your cloud-config will be transmitted, then you
-#               should use SSH authentication only.
+#               should not use this feature.
 #
-#               You have thus been warned.
 #   no_create_home: When set to true, do not create home directory.
 #   no_user_group: When set to true, do not create a group named after the user.
 #   no_log_init: When set to true, do not initialize lastlog and faillog database.

diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
@@ -1,6 +1,8 @@
 import os
 import sys
 
+import sphinx_rtd_theme
+
 from cloudinit import version
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -23,12 +25,14 @@
 # -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
+needs_sphinx = "4.0"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    "m2r",
+    "m2r2",
+    "sphinx_rtd_theme",
+    "sphinx_panels",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.viewcode",

diff --git a/doc/rtd/topics/cli.rst b/doc/rtd/topics/cli.rst
@@ -66,8 +66,8 @@ clean
 Remove cloud-init artifacts from ``/var/lib/cloud`` to simulate a clean
 instance. On reboot, cloud-init will re-run all stages as it did on first boot.
 
-* *\\-\\-logs*: optionally remove all cloud-init log files in ``/var/log/``
-* *\\-\\-reboot*: reboot the system after removing artifacts
+* ``--logs``: optionally remove all cloud-init log files in ``/var/log/``
+* ``--reboot``: reboot the system after removing artifacts
 
 
 .. _cli_collect_logs:
@@ -152,7 +152,7 @@ Can be run on the commandline, but is generally gated to run only once
 due to semaphores in ``/var/lib/cloud/instance/sem/`` and
 ``/var/lib/cloud/sem``.
 
-* *\\-\\-local*: run *init-local* stage instead of *init*
+* ``--local``: run *init-local* stage instead of *init*
 
 
 .. _cli_modules:
@@ -173,8 +173,8 @@ declared to run in various boot stages in the file
 Can be run on the command line, but each module is gated to run only once due
 to semaphores in ``/var/lib/cloud/``.
 
-* *\\-\\-mode [init|config|final]*: run *modules:init*, *modules:config* or
-  *modules:final* cloud-init stages. See :ref:`boot_stages` for more info.
+* ``--mode [init|config|final]``: run ``modules:init``, ``modules:config`` or
+  `modules:final` cloud-init stages. See :ref:`boot_stages` for more info.
 
 
 .. _cli_query:
@@ -187,13 +187,13 @@ in ``/run/cloud-init/instance-data.json``. This is a convenience command-line
 interface to reference any cached configuration metadata that cloud-init
 crawls when booting the instance. See :ref:`instance_metadata` for more info.
 
-* *\\-\\-all*: dump all available instance data as json which can be queried
-* *\\-\\-instance-data*: optional path to a different instance-data.json file
+* ``--all``: dump all available instance data as json which can be queried
+* ``--instance-data``: optional path to a different instance-data.json file
   to source for queries
-* *\\-\\-list-keys*: list available query keys from cached instance data
-* *\\-\\-format*: a string that will use jinja-template syntax to render a
+* ``--list-keys``: list available query keys from cached instance data
+* ``--format``: a string that will use jinja-template syntax to render a
   string replacing
-* *<varname>*: a dot-delimited variable path into the instance-data.json
+* ``<varname>``: a dot-delimited variable path into the instance-data.json
   object
 
 Below demonstrates how to list all top-level query keys that are standardized
@@ -256,8 +256,8 @@ single
 
 Attempt to run a single named cloud config module.
 
-* *\\-\\-name*: the cloud-config module name to run
-* *\\-\\-frequency*: optionally override the declared module frequency
+* ``--name``: the cloud-config module name to run
+* ``--frequency``: optionally override the declared module frequency
   with one of (always|once-per-instance|once)
 
 The following example re-runs the cc_set_hostname module ignoring the module
@@ -281,8 +281,8 @@ 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
+* ``--long``: detailed status information
+* ``--wait``: block until cloud-init completes
 
 Below are examples of output when cloud-init is running, showing status and
 the currently running modules, as well as when it is done.
@@ -306,5 +306,3 @@ the currently running modules, as well as when it is done.
   time: Wed, 17 Jan 2018 20:41:59 +0000
   detail:
   DataSourceNoCloud [seed=/var/lib/cloud/seed/nocloud-net][dsmode=net]
-
-.. vi: textwidth=79
diff --git a/doc/rtd/topics/datasources/configdrive.rst b/doc/rtd/topics/datasources/configdrive.rst
@@ -18,39 +18,41 @@ case then the files contained on the located drive must provide equivalents to
 what the EC2 metadata service would provide (which is typical of the version 2
 support listed below)
 
-Version 1
----------
-**Note:** Version 1 is legacy and should be considered deprecated.  Version 2
-has been supported in OpenStack since 2012.2 (Folsom).
+.. dropdown:: Version 1 (Deprecated)
 
-The following criteria are required to as a config drive:
+        **Note:** Version 1 is legacy and should be considered deprecated.
+        Version 2 has been supported in OpenStack since 2012.2 (Folsom).
 
-1. Must be formatted with `vfat`_ filesystem
-2. Must contain *one* of the following files
+        The following criteria are required to as a config drive:
 
-::
+        1. Must be formatted with `vfat`_ filesystem
+        2. Must contain *one* of the following files
+
+        ::
+
+          /etc/network/interfaces
+          /root/.ssh/authorized_keys
+          /meta.js
 
-  /etc/network/interfaces
-  /root/.ssh/authorized_keys
-  /meta.js
+        ``/etc/network/interfaces``
 
-``/etc/network/interfaces``
+            This file is laid down by nova in order to pass static networking
+            information to the guest.  Cloud-init will copy it off of the
+            config-drive and into /etc/network/interfaces (or convert it to RH
+            format) as soon as it can, and then attempt to bring up all network
+            interfaces.
 
-    This file is laid down by nova in order to pass static networking
-    information to the guest.  Cloud-init will copy it off of the config-drive
-    and into /etc/network/interfaces (or convert it to RH format) as soon as
-    it can, and then attempt to bring up all network interfaces.
+        ``/root/.ssh/authorized_keys``
 
-``/root/.ssh/authorized_keys``
+            This file is laid down by nova, and contains the ssk keys that were
+            provided to nova on instance creation (nova-boot --key ....)
 
-    This file is laid down by nova, and contains the ssk keys that were
-    provided to nova on instance creation (nova-boot --key ....)
+        ``/meta.js``
 
-``/meta.js``
+            meta.js is populated on the config-drive in response to the user
+            passing "meta flags" (nova boot --meta key=value ...). It is
+            expected to be json formatted.
 
-    meta.js is populated on the config-drive in response to the user passing
-    "meta flags" (nova boot --meta key=value ...). It is expected to be json
-    formatted.
 
 Version 2
 ---------

diff --git a/doc/rtd/topics/examples.rst b/doc/rtd/topics/examples.rst
@@ -41,13 +41,6 @@ Install and run `chef`_ recipes
    :language: yaml
    :linenos:
 
-Setup and run `puppet`_
-=======================
-
-.. literalinclude:: ../../examples/cloud-config-puppet.txt
-   :language: yaml
-   :linenos:
-
 Add primary apt repositories
 ============================
 
@@ -102,20 +95,6 @@ Adjust mount points mounted
    :language: yaml
    :linenos:
 
-Call a url when finished
-========================
-
-.. literalinclude:: ../../examples/cloud-config-phone-home.txt
-   :language: yaml
-   :linenos:
-
-Reboot/poweroff when finished
-=============================
-
-.. literalinclude:: ../../examples/cloud-config-power-state.txt
-   :language: yaml
-   :linenos:
-
 Configure instances SSH keys
 ============================
 

diff --git a/doc/rtd/topics/logging.rst b/doc/rtd/topics/logging.rst
@@ -168,7 +168,7 @@ With defaults used::
             log_serv: "10.0.4.1"
 
 
-For more information on rsyslog configuration, see :ref:`cc_rsyslog`.
+For more information on rsyslog configuration, see :ref:`rsyslog`.
 
 .. _python logging config: https://docs.python.org/3/library/logging.config.html#configuration-file-format
 .. _python logging handlers: https://docs.python.org/3/library/logging.handlers.html

diff --git a/doc/rtd/topics/security.rst b/doc/rtd/topics/security.rst
@@ -1,5 +1,6 @@
+********
+Security
+********
 .. _security:
 
 .. mdinclude:: ../../../SECURITY.md
-
-.. vi: textwidth=79