From ee4a468f1ee0247f4ac01d62849a0956d38260fa Mon Sep 17 00:00:00 2001 From: Alberto Contreras Date: Fri, 29 Apr 2022 08:31:26 +0200 Subject: [PATCH] Fix doc warnings and enable errors. --- cloudinit/config/cc_mounts.py | 15 ++++++++------- cloudinit/config/cc_phone_home.py | 4 +++- cloudinit/config/cc_rh_subscription.py | 3 ++- cloudinit/config/cc_runcmd.py | 2 +- cloudinit/config/cc_ubuntu_advantage.py | 2 +- cloudinit/config/cloud-init-schema.json | 2 +- doc/rtd/conf.py | 6 +++++- doc/rtd/topics/code_review.rst | 14 +++++++------- doc/rtd/topics/examples.rst | 15 --------------- doc/rtd/topics/faq.rst | 2 +- doc/rtd/topics/integration_tests.rst | 8 ++++---- doc/rtd/topics/logging.rst | 3 ++- doc/rtd/topics/testing.rst | 2 ++ doc/rtd/topics/tutorial.rst | 4 ++-- tests/unittests/config/test_schema.py | 2 +- tox.ini | 2 +- 16 files changed, 41 insertions(+), 45 deletions(-) diff --git a/cloudinit/config/cc_mounts.py b/cloudinit/config/cc_mounts.py index 1d4958375f7..1d05c9b983f 100644 --- a/cloudinit/config/cc_mounts.py +++ b/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"] diff --git a/cloudinit/config/cc_phone_home.py b/cloudinit/config/cc_phone_home.py index d3e91bac18c..681c3729863 100644 --- a/cloudinit/config/cc_phone_home.py +++ b/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 diff --git a/cloudinit/config/cc_rh_subscription.py b/cloudinit/config/cc_rh_subscription.py index 992bce01eaf..b742cb95183 100644 --- a/cloudinit/config/cc_rh_subscription.py +++ b/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 diff --git a/cloudinit/config/cc_runcmd.py b/cloudinit/config/cc_runcmd.py index fe56b1ed8fb..7c614f575c6 100644 --- a/cloudinit/config/cc_runcmd.py +++ b/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:: diff --git a/cloudinit/config/cc_ubuntu_advantage.py b/cloudinit/config/cc_ubuntu_advantage.py index 89d70f8fe7e..57763c3180e 100644 --- a/cloudinit/config/cc_ubuntu_advantage.py +++ b/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. """ ), diff --git a/cloudinit/config/cloud-init-schema.json b/cloudinit/config/cloud-init-schema.json index 4fe71715eb4..13c9efb1b28 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 c80c23f3aa9..1e9539a946d 100644 --- a/doc/rtd/conf.py +++ b/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 diff --git a/doc/rtd/topics/code_review.rst b/doc/rtd/topics/code_review.rst index 33aad789a9d..20c81eac9f2 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 f681f37b731..8ec8d8ab22a 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 e5784b717ac..cc6a14bbb3e 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 b2c1f5ab525..2bee6a5c337 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 `_ 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 96c30b999d7..744e9bd4210 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 5543c6f5f06..4bcbba5bcc9 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 07b8fe5d11b..e8bed272b3d 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` format, using the `runcmd`_ module to -define a command to run. When applied, it +:ref:`cloud-config` 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 6c4469085d9..54fc85ea1b6 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 ab136de3166..2391e4fa5c6 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]