docs: Fix doc warnings and enable errors (#1419)

- Remove Sphinx build warnings
- Turn Sphinx warnings into errors

LP: #1876341
SC-894

16 files changed, 41 insertions, 45 deletions

diff --git a/cloudinit/config/cc_mounts.py b/cloudinit/config/cc_mounts.py
index 1d495837..1d05c9b9 100644
--- a/cloudinit/config/cc_mounts.py
+++ b/cloudinit/config/cc_mounts.py
@@ -31,11 +31,12 @@ Any mounts that do not appear to either an attached block device or network
 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 @@ for the values in a ``mounts`` entry that are not specified, aside from the
 ``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 @@ example = dedent(
         filename: /my/swapfile
         size: auto
         maxsize: 10485760
-   """
+    """
 )
 
 distros = ["all"]
diff --git a/cloudinit/config/cc_phone_home.py b/cloudinit/config/cc_phone_home.py
index d3e91bac..681c3729 100644
--- a/cloudinit/config/cc_phone_home.py
+++ b/cloudinit/config/cc_phone_home.py
@@ -43,7 +43,9 @@ keys to post. Available keys are:
 
 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
diff --git a/cloudinit/config/cc_rh_subscription.py b/cloudinit/config/cc_rh_subscription.py
index 992bce01..b742cb95 100644
--- a/cloudinit/config/cc_rh_subscription.py
+++ b/cloudinit/config/cc_rh_subscription.py
@@ -16,7 +16,8 @@ LOG = logging.getLogger(__name__)
 
 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
diff --git a/cloudinit/config/cc_runcmd.py b/cloudinit/config/cc_runcmd.py
index fe56b1ed..7c614f57 100644
--- a/cloudinit/config/cc_runcmd.py
+++ b/cloudinit/config/cc_runcmd.py
@@ -32,7 +32,7 @@ list, it will be properly quoted. Each item is written to
 
 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::
 
diff --git a/cloudinit/config/cc_ubuntu_advantage.py b/cloudinit/config/cc_ubuntu_advantage.py
index 89d70f8f..57763c31 100644
--- a/cloudinit/config/cc_ubuntu_advantage.py
+++ b/cloudinit/config/cc_ubuntu_advantage.py
@@ -28,7 +28,7 @@ meta: MetaSchema = {
 
         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.
         """
     ),
diff --git a/cloudinit/config/cloud-init-schema.json b/cloudinit/config/cloud-init-schema.json
index 4fe71715..13c9efb1 100644
--- a/cloudinit/config/cloud-init-schema.json
+++ b/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",
diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index c80c23f3..1e9539a9 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -20,7 +20,7 @@ sys.path.insert(0, os.path.abspath("."))
 
 # General information about the project.
 project = "cloud-init"
-copyright = "2020, Canonical Ltd."
+copyright = "2022, Canonical Ltd."
 
 # -- General configuration ----------------------------------------------------
 
@@ -70,3 +70,7 @@ html_theme = "sphinx_rtd_theme"
 # 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
diff --git a/doc/rtd/topics/code_review.rst b/doc/rtd/topics/code_review.rst
index 33aad789..20c81eac 100644
--- a/doc/rtd/topics/code_review.rst
+++ b/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,7 +127,7 @@ 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
@@ -135,7 +135,7 @@ These are the steps that comprise the opening phase:
       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.
diff --git a/doc/rtd/topics/examples.rst b/doc/rtd/topics/examples.rst
index f681f37b..8ec8d8ab 100644
--- a/doc/rtd/topics/examples.rst
+++ b/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
diff --git a/doc/rtd/topics/faq.rst b/doc/rtd/topics/faq.rst
index e5784b71..cc6a14bb 100644
--- a/doc/rtd/topics/faq.rst
+++ b/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/
 
diff --git a/doc/rtd/topics/integration_tests.rst b/doc/rtd/topics/integration_tests.rst
index b2c1f5ab..2bee6a5c 100644
--- a/doc/rtd/topics/integration_tests.rst
+++ b/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
diff --git a/doc/rtd/topics/logging.rst b/doc/rtd/topics/logging.rst
index 96c30b99..744e9bd4 100644
--- a/doc/rtd/topics/logging.rst
+++ b/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
diff --git a/doc/rtd/topics/testing.rst b/doc/rtd/topics/testing.rst
index 5543c6f5..4bcbba5b 100644
--- a/doc/rtd/topics/testing.rst
+++ b/doc/rtd/topics/testing.rst
@@ -1,3 +1,5 @@
+.. _testing:
+
 *******
 Testing
 *******
diff --git a/doc/rtd/topics/tutorial.rst b/doc/rtd/topics/tutorial.rst
index 07b8fe5d..e8bed272 100644
--- a/doc/rtd/topics/tutorial.rst
+++ b/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
diff --git a/tests/unittests/config/test_schema.py b/tests/unittests/config/test_schema.py
index 6c446908..54fc85ea 100644
--- a/tests/unittests/config/test_schema.py
+++ b/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."""
diff --git a/tox.ini b/tox.ini
index ab136de3..2391e4fa 100644
--- a/tox.ini
+++ b/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]