Fix doc warnings and enable errors.

cloudinit/config/cc_mounts.py

@@ -31,11 +31,12 @@
 resource will be skipped with a log like "Ignoring nonexistent mount ...".
 
 Cloud-init will attempt to add the following mount directives if available and
-unconfigured in `/etc/fstab`:
+unconfigured in `/etc/fstab`::
+
     mounts:
-    - ["ephemeral0", "/mnt", "auto",
-       "defaults,nofail,x-systemd.requires=cloud-init.service", "0", "2"]
-    - ["swap", "none", "swap", "sw", "0", "0"]
+        - ["ephemeral0", "/mnt", "auto",\
+"defaults,nofail,x-systemd.requires=cloud-init.service", "0", "2"]
+        - ["swap", "none", "swap", "sw", "0", "0"]
 
 In order to remove a previously listed mount, an entry can be added to
 the `mounts` list containing ``fs_spec`` for the device to be removed but no
@@ -46,8 +47,8 @@
 ``fs_spec`` and the ``fs_file``. If specified, this must be a list containing 6
 values. It defaults to::
 
-    mount_default_fields: [none, none, "auto",
-        "defaults,nofail,x-systemd.requires=cloud-init.service", "0", "2"]
+    mount_default_fields: [none, none, "auto",\
+"defaults,nofail,x-systemd.requires=cloud-init.service", "0", "2"]
 
 Non-systemd init systems will vary in ``mount_default_fields``.
 
@@ -72,7 +73,7 @@
         filename: /my/swapfile
         size: auto
         maxsize: 10485760
-   """
+    """
 )
 
 distros = ["all"]

cloudinit/config/cc_phone_home.py

@@ -43,7 +43,9 @@
 
 Data is sent as ``x-www-form-urlencoded`` arguments.
 
-**Example HTTP POST**::
+**Example HTTP POST**:
+
+.. code-block:: http
 
     POST / HTTP/1.1
     Content-Length: 1337

cloudinit/config/cc_rh_subscription.py

@@ -16,7 +16,8 @@
 
 MODULE_DESCRIPTION = """\
 Register a Red Hat system either by username and password *or* activation and
-org. Following a sucessful registration, you can:
+org. Following a successful registration, you can:
+
  - auto-attach subscriptions
  - set the service level
  - add subscriptions based on pool id

cloudinit/config/cc_runcmd.py

@@ -32,7 +32,7 @@
 
 Note that the ``runcmd`` module only writes the script to be run
 later. The module that actually runs the script is ``scripts-user``
-in the :ref:`Final` boot stage.
+in the :ref:`topics/boot:Final` boot stage.
 
 .. note::
 

cloudinit/config/cc_ubuntu_advantage.py

@@ -28,7 +28,7 @@
 
         Note that when enabling FIPS or FIPS updates you will need to schedule
         a reboot to ensure the machine is running the FIPS-compliant kernel.
-        See :ref:`Power State Change` for information on how to configure
+        See `Power State Change`_ for information on how to configure
         cloud-init to perform this reboot.
         """
     ),

cloudinit/config/cloud-init-schema.json

@@ -1943,7 +1943,7 @@
             "enabled": {
               "type": "boolean",
               "default": true,
-              "description": "If true, will read host keys from /etc/ssh/*.pub and publish them to the datasource (if supported). Default: ``true``"
+              "description": "If true, will read host keys from ``/etc/ssh/*.pub`` and publish them to the datasource (if supported). Default: ``true``"
             },
             "blacklist": {
               "type": "array",

doc/rtd/conf.py

@@ -20,7 +20,7 @@
 
 # General information about the project.
 project = "cloud-init"
-copyright = "2020, Canonical Ltd."
+copyright = "2022, Canonical Ltd."
 
 # -- General configuration ----------------------------------------------------
 
@@ -70,3 +70,7 @@
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 html_logo = "static/logo.png"
+
+# Make sure the target is unique
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2

doc/rtd/topics/code_review.rst

@@ -115,7 +115,7 @@ request and meeting the prerequisites laid out above.
 
 If they need help understanding the prerequisites, or help meeting the
 prerequisites, then they can (and should!) ask for help.  See the
-:ref:`Asking For Help` section above for the ways to do that.
+`Asking For Help`_ section above for the ways to do that.
 
 These are the steps that comprise the opening phase:
 
@@ -127,15 +127,15 @@ These are the steps that comprise the opening phase:
       The **Proposer** is expected to fix CI failures.  If the
       **Proposer** doesn't understand the nature of the failures they
       are seeing, they should comment in the PR to request assistance,
-      or use another way of :ref:`Asking For Help`.
+      or use another way of `Asking For Help`_.
 
       (Note that if assistance is not requested, the **Committers**
       will assume that the **Proposer** is working on addressing the
       failures themselves.  If you require assistance, please do ask
       for help!)
 
    CI passes
-      Move on to the :ref:`Review phase`.
+      Move on to the `Review Phase`_.
 
 Review Phase
 ============
@@ -144,7 +144,7 @@ In this phase, the **Proposer** and the **Reviewers** will iterate
 together to, hopefully, get the PR merged into the cloud-init codebase.
 There are three potential outcomes: merged, rejected permanently, and
 temporarily closed.  (The first two are covered in this section; see
-:ref:`Inactive Pull Requests` for details about temporary closure.)
+`Inactive Pull Requests`_ for details about temporary closure.)
 
 (In the below, when the verbs "merge" or "squash merge" are used, they
 should be understood to mean "squash merged using the GitHub UI", which
@@ -177,8 +177,8 @@ These are the steps that comprise the review phase:
    in one of the following:
 
    Approve
-     If the submitted PR meets all of the :ref:`Prerequisites for
-     Landing Pull Requests` and passes code review, then the
+     If the submitted PR meets all of the `Prerequisites for
+     Landing Pull Requests`_ and passes code review, then the
      **Committer** will squash merge immediately.
 
      There may be circumstances where a PR should not be merged
@@ -252,5 +252,5 @@ of inactivity.  It will be closed after a further 7 days of inactivity.
 
 These closes are not considered permanent, and the closing message
 should reflect this for the **Proposer**. However, if a PR is reopened,
-it should effectively enter the :ref:`Opening phase` again, as it may
+it should effectively enter the `Opening phase`_ again, as it may
 need some work done to get CI passing again.

doc/rtd/topics/examples.rst

@@ -59,14 +59,6 @@ Run commands on first boot
    :language: yaml
    :linenos:
 
-
-Alter the completion message
-============================
-
-.. literalinclude:: ../../examples/cloud-config-final-message.txt
-   :language: yaml
-   :linenos:
-
 Install arbitrary packages
 ==========================
 
@@ -130,13 +122,6 @@ Create partitions and filesystems
    :language: yaml
    :linenos:
 
-Grow partitions
-===============
-
-.. literalinclude:: ../../examples/cloud-config-growpart.txt
-   :language: yaml
-   :linenos:
-
 .. _chef: http://www.chef.io/chef/
 .. _puppet: http://puppetlabs.com/
 .. vi: textwidth=79

doc/rtd/topics/faq.rst

@@ -278,7 +278,7 @@ configuration, including network configuration and metadata:
 
 See the :ref:`network_config_v2` page for details on the format and config of
 network configuration. To learn more about the possible values for metadata,
-check out the :ref:`nocloud` page.
+check out the :ref:`datasource_nocloud` page.
 
 .. _cloud-utils: https://github.com/canonical/cloud-utils/
 

doc/rtd/topics/integration_tests.rst

@@ -22,7 +22,7 @@ marks can be used to limit tests to particular platforms. The
 client fixture can be used to interact with the launched
 test instance.
 
-See :ref:`Examples` section for examples.
+See `Examples`_ section for examples.
 
 Test Execution
 ==============
@@ -74,7 +74,7 @@ Image Selection
 
 Each integration testing run uses a single image as its basis.  This
 image is configured using the ``OS_IMAGE`` variable; see
-:ref:`Configuration` for details of how configuration works.
+`Configuration`_ for details of how configuration works.
 
 ``OS_IMAGE`` can take two types of value: an Ubuntu series name (e.g.
 "focal"), or an image specification.  If an Ubuntu series name is
@@ -139,13 +139,13 @@ Integration tests rely heavily on fixtures to do initial test setup.
 One or more of these fixtures will be used in almost every integration test.
 
 Details such as the cloud platform or initial image to use are determined
-via what is specified in the :ref:`Configuration`.
+via what is specified in the `Configuration`_.
 
 client
 ------
 The ``client`` fixture should be used for most test cases. It ensures:
 
-- All setup performed by :ref:`session_cloud` and :ref:`setup_image`
+- All setup performed by `session_cloud`_ and `setup_image`_
 - `Pytest marks <https://github.com/canonical/cloud-init/blob/af7eb1deab12c7208853c5d18b55228e0ba29c4d/tests/integration_tests/conftest.py#L220-L224>`_
   used during instance creation are obtained and applied
 - The test instance is launched

doc/rtd/topics/logging.rst

@@ -168,7 +168,8 @@ With defaults used::
             log_serv: "10.0.4.1"
 
 
-For more information on rsyslog configuration, see :ref:`rsyslog`.
+For more information on rsyslog configuration, see
+:ref:`topics/modules: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

doc/rtd/topics/testing.rst

@@ -1,3 +1,5 @@
+.. _testing:
+
 *******
 Testing
 *******

doc/rtd/topics/tutorial.rst

@@ -47,8 +47,8 @@ following file on your local filesystem at ``/tmp/my-user-data``:
       - echo 'Hello, World!' > /var/tmp/hello-world.txt
 
 Here we are defining our cloud-init user data in the
-:ref:`cloud-config<cloud Config Data>` format, using the `runcmd`_ module to
-define a command to run. When applied, it
+:ref:`cloud-config<topics/format:Cloud Config Data>` format, using the
+`runcmd`_ module to define a command to run. When applied, it
 should write ``Hello, World!`` to ``/var/tmp/hello-world.txt``.
 
 Launch a container with our user data

tests/unittests/config/test_schema.py

@@ -210,7 +210,7 @@ class Test_SchemapathForCloudconfig:
             (b"a:\n a1:\n\n  aa1: aa1v\n", {"a": 1, "a.a1": 2, "a.a1.aa1": 4}),
         ),
     )
-    def test_schemapaths_representatative_of_source_yaml(
+    def test_schemapaths_representative_of_source_yaml(
         self, source_content, expected
     ):
         """Validate schemapaths dict accurately represents source YAML line."""

tox.ini

@@ -143,7 +143,7 @@ commands = {[testenv:py3]commands}
 deps =
     -r{toxinidir}/doc-requirements.txt
 commands =
-    {envpython} -m sphinx {posargs:doc/rtd doc/rtd_html}
+    {envpython} -m sphinx {posargs:-W doc/rtd doc/rtd_html}
     doc8 doc/rtd
 
 [testenv:tip-flake8]