diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 65c6d54f686e..4d419a2eff46 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -75,3 +75,10 @@ repos: | nova/virt/libvirt/host.py | nova/virt/libvirt/utils.py ) + - repo: https://github.com/sphinx-contrib/sphinx-lint + rev: v0.6.8 + hooks: + - id: sphinx-lint + args: [--enable=default-role] + files: ^doc/|releasenotes|api-guide + types: [rst] diff --git a/doc/source/admin/cells.rst b/doc/source/admin/cells.rst index 19878b1e8445..e7e96aabd5f9 100644 --- a/doc/source/admin/cells.rst +++ b/doc/source/admin/cells.rst @@ -559,7 +559,7 @@ URL (using ``rabbit://bob:s3kret@myhost:123/nova?sync=true#extra``): - Meaning - Part of example URL * - ``scheme`` - - The part before the `://` + - The part before the ``://`` - ``rabbit`` * - ``username`` - The username part of the credentials diff --git a/doc/source/admin/compute-node-identification.rst b/doc/source/admin/compute-node-identification.rst index 31d4802d0b7c..8fcca1502bb9 100644 --- a/doc/source/admin/compute-node-identification.rst +++ b/doc/source/admin/compute-node-identification.rst @@ -12,7 +12,7 @@ configuration file were used. The 2023.1 and later compute node identification file must remain unchanged during the lifecycle of the compute node. Changing the value or removing the file will result in a failure to start and may require advanced techniques -for recovery. The file is read once at `nova-compute`` startup, at which point +for recovery. The file is read once at ``nova-compute`` startup, at which point it is validated for formatting and the corresponding node is located or created in the database. @@ -27,7 +27,7 @@ as the (UUID-based) identity and mapping of compute nodes to compute manager service hosts is dynamic. In that case, no single node identity is maintained by the compute host and thus no identity file is read or written. Thus none of the sections below apply to hosts with :oslo.config:option:`compute_driver` -set to `ironic`. +set to ``ironic``. Self-provisioning of the node identity -------------------------------------- diff --git a/doc/source/admin/configuration/hypervisor-vmware.rst b/doc/source/admin/configuration/hypervisor-vmware.rst index dec7642f31d6..06d3d912c712 100644 --- a/doc/source/admin/configuration/hypervisor-vmware.rst +++ b/doc/source/admin/configuration/hypervisor-vmware.rst @@ -928,7 +928,7 @@ cached images are stored. have a shared file system. You can automatically purge unused images after a specified period of time. To -configure this action, set these options in the :oslo.config:group`image_cache` +configure this action, set these options in the :oslo.config:group:`image_cache` section in the ``nova.conf`` file: * :oslo.config:option:`image_cache.remove_unused_base_images` diff --git a/doc/source/admin/cpu-models.rst b/doc/source/admin/cpu-models.rst index aa133dd03dcc..e81b03e89bc0 100644 --- a/doc/source/admin/cpu-models.rst +++ b/doc/source/admin/cpu-models.rst @@ -142,7 +142,7 @@ If :oslo.config:option:`cpu_mode=none `, libvirt does not specify a CPU model. Instead, the hypervisor chooses the default model. The ``none`` CPU model is the default for all non-KVM/QEMU hypervisors. -(:oslo.config:option:`libvirt.virt_type`\ !=``kvm``/``qemu``) +(:oslo.config:option:`libvirt.virt_type`\ != ``kvm`` / ``qemu``) .. _cpu-models: diff --git a/doc/source/admin/cpu-topologies.rst b/doc/source/admin/cpu-topologies.rst index 7b0c6ef41f65..ac88c4b5779d 100644 --- a/doc/source/admin/cpu-topologies.rst +++ b/doc/source/admin/cpu-topologies.rst @@ -764,7 +764,7 @@ tuned. That being said, we also provide a way to automatically change the governors on the fly, as explained below. .. important:: - Some OS platforms don't support `cpufreq` resources in sysfs, so the + Some OS platforms don't support ``cpufreq`` resources in sysfs, so the ``governor`` strategy could be not available. Please verify if your OS supports scaling govenors before modifying the configuration option. diff --git a/doc/source/admin/evacuate.rst b/doc/source/admin/evacuate.rst index 18796d9c237c..d8a017b5b59f 100644 --- a/doc/source/admin/evacuate.rst +++ b/doc/source/admin/evacuate.rst @@ -110,4 +110,4 @@ instances up and running. If the instance task state is not None, evacuation will be possible. However, depending on the ongoing operation, there may be clean up required in other services which the instance was using, such as neutron, cinder, glance, or - the storage backend. \ No newline at end of file + the storage backend. diff --git a/doc/source/admin/libvirt-misc.rst b/doc/source/admin/libvirt-misc.rst index eb3d20b47940..02e287bbaeb4 100644 --- a/doc/source/admin/libvirt-misc.rst +++ b/doc/source/admin/libvirt-misc.rst @@ -153,11 +153,11 @@ realtime guests but can also be enabled explicitly using the ``hw:locked_memory`` extra spec (or use ``hw_locked_memory`` image property). ``hw:locked_memory`` (also ``hw_locked_memory`` image property) accept boolean values in string format like 'true' or 'false' value. -It will raise `FlavorImageLockedMemoryConflict` exception if both flavor and +It will raise ``FlavorImageLockedMemoryConflict`` exception if both flavor and image property are specified but with different boolean values. This will only be allowed if you have also set ``hw:mem_page_size``, so we can ensure that the scheduler can actually account for this correctly -and prevent out of memory events. Otherwise, will raise `LockMemoryForbidden` +and prevent out of memory events. Otherwise, will raise ``LockMemoryForbidden`` exception. .. code:: console diff --git a/doc/source/admin/live-migration-usage.rst b/doc/source/admin/live-migration-usage.rst index dc27574f910a..2b05a004a6d2 100644 --- a/doc/source/admin/live-migration-usage.rst +++ b/doc/source/admin/live-migration-usage.rst @@ -230,7 +230,7 @@ taken against a VM after 2. ``force_complete``: The compute service will either pause the VM or trigger post-copy depending on if post copy is enabled and available (:oslo.config:option:`libvirt.live_migration_permit_post_copy` is set to - `True`). This is similar to using API + ``True``). This is similar to using API ``POST /servers/{server_id}/migrations/{migration_id}/action (force_complete)``. You can also read the diff --git a/doc/source/admin/manage-volumes.rst b/doc/source/admin/manage-volumes.rst index d274e8db7c05..8a941368549c 100644 --- a/doc/source/admin/manage-volumes.rst +++ b/doc/source/admin/manage-volumes.rst @@ -173,26 +173,26 @@ Admins may also refresh an existing volume attachment using the following include orchestrating the shutdown of an instance and refreshing volume attachments among other things. -To begin the admin can use the `volume_attachment show` subcommand to dump +To begin the admin can use the ``volume_attachment show`` subcommand to dump existing details of the attachment directly from the Nova database. This -includes the stashed `connection_info` not shared by the API. +includes the stashed ``connection_info`` not shared by the API. .. code-block:: shell $ nova-manage volume_attachment show 216f9481-4c9d-4530-b865-51cedfa4b8e7 8b9b3491-f083-4485-8374-258372f3db35 --json | jq .attachment_id "d338fb38-cfd5-461f-8753-145dcbdb6c78" -If the stored `connection_info` or `attachment_id` are incorrect then the +If the stored ``connection_info`` or ``attachment_id`` are incorrect then the admin may want to refresh the attachment to the compute host entirely by recreating the Cinder volume attachment record(s) and pulling down fresh -`connection_info`. To do this we first need to ensure the instance is stopped: +``connection_info``. To do this we first need to ensure the instance is stopped: .. code-block:: shell $ openstack server stop 216f9481-4c9d-4530-b865-51cedfa4b8e7 Once stopped the host connector of the compute hosting the instance has to be -fetched using the `volume_attachment get_connector` subcommand: +fetched using the ``volume_attachment get_connector`` subcommand: .. code-block:: shell @@ -204,7 +204,7 @@ fetched using the `volume_attachment get_connector` subcommand: the host connector into the main refresh command. Unfortunately until then it must remain a separate manual step. -We can then provide this connector to the `volume_attachment refresh` +We can then provide this connector to the ``volume_attachment refresh`` subcommand. This command will connect to the compute, disconnect any host volume connections, delete the existing Cinder volume attachment, recreate the volume attachment and finally update Nova's database. diff --git a/doc/source/admin/node-down.rst b/doc/source/admin/node-down.rst index 58311e808887..cf85c2c1e414 100644 --- a/doc/source/admin/node-down.rst +++ b/doc/source/admin/node-down.rst @@ -220,7 +220,7 @@ After power resumes and all hardware components restart: stop at the plymouth stage. This is expected behavior. DO NOT reboot a second time. - Instance state at this stage depends on whether you added an `/etc/fstab` + Instance state at this stage depends on whether you added an ``/etc/fstab`` entry for that volume. Images built with the cloud-init package remain in a ``pending`` state, while others skip the missing volume and start. You perform this step to ask Compute to reboot every instance so that the diff --git a/doc/source/admin/quotas.rst b/doc/source/admin/quotas.rst index 8dce1ce48b33..19b5b28c6778 100644 --- a/doc/source/admin/quotas.rst +++ b/doc/source/admin/quotas.rst @@ -86,7 +86,7 @@ are made in order: .. note:: The API sets the limit in the ``quota_classes`` table. Once a default limit - is set via the `default` quota class, that takes precedence over any + is set via the ``default`` quota class, that takes precedence over any changes to that resource limit in the configuration options. In other words, once you've changed things via the API, you either have to keep those synchronized with the configuration values or remove the default diff --git a/doc/source/admin/scheduling.rst b/doc/source/admin/scheduling.rst index c872c7163fe9..5fb811ee6e80 100644 --- a/doc/source/admin/scheduling.rst +++ b/doc/source/admin/scheduling.rst @@ -269,7 +269,7 @@ Refer to :doc:`/admin/aggregates` for more information. Filters host by disk allocation with a per-aggregate ``max_io_ops_per_host`` value. If the per-aggregate value is not found, the value falls back to the global setting defined by the -`:oslo.config:option:`filter_scheduler.max_io_ops_per_host` config option. +:oslo.config:option:`filter_scheduler.max_io_ops_per_host` config option. If the host is in more than one aggregate and more than one value is found, the minimum value will be used. @@ -906,7 +906,7 @@ that are not and are not available using the respectively. Starting with the Stein release, if per-aggregate value with the key -`metrics_weight_multiplier` is found, this value would be chosen as the +``metrics_weight_multiplier`` is found, this value would be chosen as the metrics weight multiplier. Otherwise, it will fall back to the :oslo.config:option:`metrics.weight_multiplier`. If more than one value is found for a host in aggregate metadata, the minimum value will @@ -1029,7 +1029,7 @@ value will be used. Weighs hosts based on which cell they are in. "Local" cells are preferred when moving an instance. -If per-aggregate value with the key `cross_cell_move_weight_multiplier` is +If per-aggregate value with the key ``cross_cell_move_weight_multiplier`` is found, this value would be chosen as the cross-cell move weight multiplier. Otherwise, it will fall back to the :oslo.config:option:`filter_scheduler.cross_cell_move_weight_multiplier`. If @@ -1050,7 +1050,7 @@ hosts with different hypervisors. For example, the ironic virt driver uses the ironic API micro-version as the hypervisor version for a given node. The libvirt driver uses the libvirt version -i.e. Libvirt `7.1.123` becomes `700100123` vs Ironic `1.82` becomes `1`. +i.e. Libvirt ``7.1.123`` becomes ``700100123`` vs Ironic ``1.82`` becomes ``1``. If you have a mixed virt driver deployment in the ironic vs non-ironic case nothing special needs to be done. ironic nodes are scheduled using custom diff --git a/doc/source/admin/support-compute.rst b/doc/source/admin/support-compute.rst index 31e32fd1ddc4..7cc80c90a0b9 100644 --- a/doc/source/admin/support-compute.rst +++ b/doc/source/admin/support-compute.rst @@ -206,7 +206,7 @@ Problem You can view the log output of running instances from either the :guilabel:`Log` tab of the dashboard or the output of :command:`nova console-log`. In some cases, the log output of a running Linux instance will be -empty or only display a single character (for example, the `?` character). +empty or only display a single character (for example, the ``?`` character). This occurs when the Compute service attempts to retrieve the log output of the instance via a serial console while the instance itself is not configured to diff --git a/doc/source/admin/upgrades.rst b/doc/source/admin/upgrades.rst index 61fd0cf2587f..8d80ec0dcdd8 100644 --- a/doc/source/admin/upgrades.rst +++ b/doc/source/admin/upgrades.rst @@ -51,7 +51,7 @@ same time. As of OpenStack 2023.1 (Antelope), Nova supports the coexistence of N and N-2 (Yoga) :program:`nova-compute` or :program:`nova-conductor` services in - the same deployment. The `nova-conductor`` service will fail to start when + the same deployment. The ``nova-conductor`` service will fail to start when a ``nova-compute`` service that is older than the support envelope is detected. This varies by release and the support envelope will be explained in the release notes. Similarly, in a :doc:`deployment with multiple cells @@ -116,7 +116,7 @@ same time. #. After maintenance window: * Once all services are running the new code, double check in the DB that - there are no old orphaned service records using `nova service-list`. + there are no old orphaned service records using ``nova service-list``. * Now that all services are upgraded, we need to send the SIG_HUP signal, so all the services clear any cached service version data. When a new service diff --git a/doc/source/configuration/policy-concepts.rst b/doc/source/configuration/policy-concepts.rst index 3908138ecffa..ec52077fa844 100644 --- a/doc/source/configuration/policy-concepts.rst +++ b/doc/source/configuration/policy-concepts.rst @@ -255,7 +255,7 @@ overridden in the policy.yaml file but scope is not override-able. read-only operation within project. For example: Get server. #. PROJECT_MEMBER_OR_ADMIN: ``admin`` or ``member`` role on ``project`` scope. Such policy rules are default to most of the owner level APIs and align - with `member` role legacy admin can continue to access those APIs. + with ``member`` role legacy admin can continue to access those APIs. #. PROJECT_READER_OR_ADMIN: ``admin`` or ``reader`` role on ``project`` scope. Such policy rules are default to most of the read only APIs so that legacy admin can continue to access those APIs. diff --git a/doc/source/contributor/blueprints.rst b/doc/source/contributor/blueprints.rst index b5e1cc4adde9..3098aa570064 100644 --- a/doc/source/contributor/blueprints.rst +++ b/doc/source/contributor/blueprints.rst @@ -40,7 +40,7 @@ Guidelines for when a feature doesn't need a spec. When a blueprint does not require a spec it still needs to be approved before the code which implements the blueprint is merged. Specless blueprints are discussed and potentially approved during -the `Open Discussion` portion of the weekly `nova IRC meeting`_. See +the ``Open Discussion`` portion of the weekly `nova IRC meeting`_. See `trivial specifications`_ for more details. Project Priorities diff --git a/doc/source/contributor/development-environment.rst b/doc/source/contributor/development-environment.rst index fab18a94e7c8..337b7296ef59 100644 --- a/doc/source/contributor/development-environment.rst +++ b/doc/source/contributor/development-environment.rst @@ -177,7 +177,7 @@ function: As a reminder, the hooks are optional and you are not enforced to run them. You can either not install pre-commit or skip the hooks once by using the -`--no-verify` flag on `git commit`. +``--no-verify`` flag on ``git commit``. Using a remote debugger ======================= diff --git a/doc/source/contributor/documentation.rst b/doc/source/contributor/documentation.rst index acddf831cadd..e435ac9c93d9 100644 --- a/doc/source/contributor/documentation.rst +++ b/doc/source/contributor/documentation.rst @@ -47,7 +47,7 @@ every stable release (e.g. ``pike``). unimproved as we address content in ``latest``. The ``api-ref`` and ``api-guide`` publish only from master to a single site on -`docs.openstack.org`. As such, they are effectively branchless. +``docs.openstack.org``. As such, they are effectively branchless. Guidelines for consumable docs ============================== diff --git a/doc/source/contributor/microversions.rst b/doc/source/contributor/microversions.rst index e06a75d7d3ae..2f7d1e2006c5 100644 --- a/doc/source/contributor/microversions.rst +++ b/doc/source/contributor/microversions.rst @@ -380,7 +380,7 @@ necessary to add changes to other places which describe your change: env ``api-samples`` or run test with env var ``GENERATE_SAMPLES`` True. * Update the `API Reference`_ documentation as appropriate. The source is - located under `api-ref/source/`. + located under ``api-ref/source/``. * If the microversion changes servers related APIs, update the ``api-guide/source/server_concepts.rst`` accordingly. diff --git a/doc/source/contributor/testing/libvirt-numa.rst b/doc/source/contributor/testing/libvirt-numa.rst index cf738b45a991..614316cf409f 100644 --- a/doc/source/contributor/testing/libvirt-numa.rst +++ b/doc/source/contributor/testing/libvirt-numa.rst @@ -284,7 +284,7 @@ And now back on the physical host edit the guest config as root: $ sudo virsh edit f29x86_64 -The first thing is to change the `` block to do passthrough of the host +The first thing is to change the ```` block to do passthrough of the host CPU. In particular this exposes the "SVM" or "VMX" feature bits to the guest so that "Nested KVM" can work. At the same time we want to define the NUMA topology of the guest. To make things interesting we're going to give the guest @@ -547,7 +547,7 @@ Testing instance boot with no NUMA topology requested For the sake of backwards compatibility, if the NUMA filter is enabled, but the flavor/image does not have any NUMA settings requested, it should be assumed that the guest will have a single NUMA node. The guest should be locked to a -single host NUMA node too. Boot a guest with the `m1.tiny` flavor to test this +single host NUMA node too. Boot a guest with the ``m1.tiny`` flavor to test this condition: .. code-block:: bash diff --git a/doc/source/contributor/testing/serial-console.rst b/doc/source/contributor/testing/serial-console.rst index e5c4c461f91a..124c7181b198 100644 --- a/doc/source/contributor/testing/serial-console.rst +++ b/doc/source/contributor/testing/serial-console.rst @@ -26,7 +26,7 @@ Starting a new instance. # cd devstack && . openrc # nova boot --flavor 1 --image cirros-0.3.2-x86_64-uec cirros1 -Nova provides a command `nova get-serial-console` which will returns a +Nova provides a command ``nova get-serial-console`` which will returns a URL with a valid token to connect to the serial console of VMs. .. code-block:: bash diff --git a/doc/source/reference/attach-volume.rst b/doc/source/reference/attach-volume.rst index 8bf24d7fc597..6465e92113dc 100644 --- a/doc/source/reference/attach-volume.rst +++ b/doc/source/reference/attach-volume.rst @@ -32,4 +32,4 @@ itself. This final ``connect_volume`` lock also being held when detaching and disconnecting a volume from the host by ``os-brick``. .. image:: /_static/images/attach_volume.svg - :alt: Attach volume workflow \ No newline at end of file + :alt: Attach volume workflow diff --git a/doc/source/reference/policy-enforcement.rst b/doc/source/reference/policy-enforcement.rst index 22d305e8c930..0457763875cd 100644 --- a/doc/source/reference/policy-enforcement.rst +++ b/doc/source/reference/policy-enforcement.rst @@ -172,7 +172,7 @@ broken into ``compute:foobar:create``, ``compute:foobar:update``, ``compute:foobar:list``, ``compute:foobar:get``, and ``compute:foobar:delete``. Breaking policies down this way allows us to set read-only policies for readable operations or use another default role for creation and management of -`foobar` resources. The oslo.policy library has `examples`_ that show how to do +``foobar`` resources. The oslo.policy library has `examples`_ that show how to do this using deprecated policy rules. .. _examples: https://docs.openstack.org/oslo.policy/latest/reference/api/oslo_policy.policy.html#oslo_policy.policy.DeprecatedRule diff --git a/doc/source/reference/scheduling.rst b/doc/source/reference/scheduling.rst index 81e99c17b970..418199a41e2d 100644 --- a/doc/source/reference/scheduling.rst +++ b/doc/source/reference/scheduling.rst @@ -77,7 +77,7 @@ As the above diagram illustrates, scheduling works like so: from the ranked list that are in the same cell as the selected host, which can be used by the cell conductor in the event that the build on the selected host fails for some reason. The number of alternates is determined - by the configuration option `scheduler.max_attempts`. + by the configuration option ``scheduler.max_attempts``. #. Scheduler creates two list structures for each requested instance: one for the hosts (selected + alternates), and the other for their matching diff --git a/doc/source/reference/services.rst b/doc/source/reference/services.rst index 99bb31bcdcd6..3275f9b9649b 100644 --- a/doc/source/reference/services.rst +++ b/doc/source/reference/services.rst @@ -50,6 +50,6 @@ Implementation-Specific Drivers A manager will generally load a driver for some of its tasks. The driver is responsible for specific implementation details. Anything running shell commands on a host, or dealing with other non-python code should probably be happening in a driver. -Drivers should not touch the database as the database management is done inside `nova-conductor`. +Drivers should not touch the database as the database management is done inside ``nova-conductor``. It usually makes sense to define an Abstract Base Class for the specific driver (i.e. VolumeDriver), to define the methods that a different driver would need to implement. diff --git a/doc/source/user/block-device-mapping.rst b/doc/source/user/block-device-mapping.rst index 361f4bcf0190..1fdbbb4358bf 100644 --- a/doc/source/user/block-device-mapping.rst +++ b/doc/source/user/block-device-mapping.rst @@ -40,7 +40,7 @@ When we talk about block device mapping, we usually refer to one of two things format as the 'API BDMs' from now on. 2.2 The virt driver format - this is the format defined by the classes in - :mod: `nova.virt.block_device`. This format is used and expected by the code + :mod:`nova.virt.block_device`. This format is used and expected by the code in the various virt drivers. These classes, in addition to exposing a different format (mimicking the Python dict interface), also provide a place to bundle some functionality common to certain types of block devices (for @@ -66,8 +66,8 @@ mirrored that of the EC2 API. During the Havana release of Nova, block device handling code, and in turn the block device mapping structure, had work done on improving the generality and usefulness. These improvements included exposing additional details and features in the API. In order to facilitate this, a new -extension was added to the v2 API called `BlockDeviceMappingV2Boot` [2]_, that -added an additional `block_device_mapping_v2` field to the instance boot API +extension was added to the v2 API called ``BlockDeviceMappingV2Boot`` [2]_, that +added an additional ``block_device_mapping_v2`` field to the instance boot API request. Block device mapping v1 (aka legacy) @@ -82,14 +82,14 @@ this page), and would accept only: * Type field - used only to distinguish between volumes and Cinder volume snapshots * Optional size field -* Optional `delete_on_termination` flag +* Optional ``delete_on_termination`` flag While all of Nova internal code only uses and stores the new data structure, we still need to handle API requests that use the legacy format. This is handled by the Nova API service on every request. As we will see later, since block device mapping information can also be stored in the image metadata in Glance, this is another place where we need to handle the v1 format. The code to handle -legacy conversions is part of the :mod: `nova.block_device` module. +legacy conversions is part of the :mod:`nova.block_device` module. Intermezzo - problem with device names ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -110,7 +110,7 @@ for the features mentioned above (and preferably only then). Another use for specifying the device name was to allow the "boot from volume" functionality, by specifying a device name that matches the root device name -for the instance (usually `/dev/vda`). +for the instance (usually ``/dev/vda``). Currently (mid Liberty) users are discouraged from specifying device names for all calls requiring or allowing block device mapping, except when trying to @@ -131,19 +131,19 @@ fields (in addition to the ones that were already there): * source_type - this can have one of the following values: - * `image` - * `volume` - * `snapshot` - * `blank` + * ``image`` + * ``volume`` + * ``snapshot`` + * ``blank`` * destination_type - this can have one of the following values: - * `local` - * `volume` + * ``local`` + * ``volume`` * guest_format - Tells Nova how/if to format the device prior to attaching, should be only used with blank local images. Denotes a swap disk if the value - is `swap`. + is ``swap``. * device_name - See the previous section for a more in depth explanation of this - currently best left empty (not specified that is), unless the user @@ -153,8 +153,8 @@ fields (in addition to the ones that were already there): get changed by the driver. * disk_bus and device_type - low level details that some hypervisors (currently - only libvirt) may support. Some example disk_bus values can be: `ide`, `usb`, - `virtio`, `scsi`, while device_type may be `disk`, `cdrom`, `floppy`, `lun`. + only libvirt) may support. Some example disk_bus values can be: ``ide``, ``usb``, + ``virtio``, ``scsi``, while device_type may be ``disk``, ``cdrom``, ``floppy``, ``lun``. This is not an exhaustive list as it depends on the virtualization driver, and may change as more support is added. Leaving these empty is the most common thing to do. @@ -185,28 +185,28 @@ Combination of the ``source_type`` and ``destination_type`` will define the kind of block device the entry is referring to. The following combinations are supported: -* `image` -> `local` - this is only currently reserved for the entry +* ``image`` -> ``local`` - this is only currently reserved for the entry referring to the Glance image that the instance is being booted with (it should also be marked as a boot device). It is also worth noting that an API request that specifies this, also has to provide the - same Glance uuid as the `image_ref` parameter to the boot request + same Glance uuid as the ``image_ref`` parameter to the boot request (this is done for backwards compatibility and may be changed in the future). This functionality might be extended to specify additional Glance images to be attached to an instance after boot (similar to kernel/ramdisk images) but this functionality is not supported by any of the current drivers. -* `volume` -> `volume` - this is just a Cinder volume to be attached to the +* ``volume`` -> ``volume`` - this is just a Cinder volume to be attached to the instance. It can be marked as a boot device. -* `snapshot` -> `volume` - this works exactly as passing `type=snap` does. +* ``snapshot`` -> ``volume`` - this works exactly as passing ``type=snap`` does. It would create a volume from a Cinder volume snapshot and attach that volume to the instance. Can be marked bootable. -* `image` -> `volume` - As one would imagine, this would download a Glance +* ``image`` -> ``volume`` - As one would imagine, this would download a Glance image to a cinder volume and attach it to an instance. Can also be marked as bootable. This is really only a shortcut for creating a volume out of an image before booting an instance with the newly created volume. -* `blank` -> `volume` - Creates a blank Cinder volume and attaches it. This +* ``blank`` -> ``volume`` - Creates a blank Cinder volume and attaches it. This will also require the volume size to be set. -* `blank` -> `local` - Depending on the guest_format field (see below), +* ``blank`` -> ``local`` - Depending on the guest_format field (see below), this will either mean an ephemeral blank disk on hypervisor local storage, or a swap disk (instances can have only one of those). @@ -216,13 +216,13 @@ will do basic validation to make sure that the requested block device mapping is valid before accepting a boot request. .. [1] In addition to the BlockDeviceMapping Nova object, we also have the - BlockDeviceDict class in :mod: `nova.block_device` module. This class + BlockDeviceDict class in :mod:`nova.block_device` module. This class handles transforming and validating the API BDM format. .. [2] This work predates API microversions and thus the only way to add it was by means of an API extension. .. [3] This is a feature that the EC2 API offers as well and has been in Nova for a long time, although it has been broken in several releases. More info - can be found on `this bug ` + can be found on `this bug `_ FAQs diff --git a/doc/source/user/certificate-validation.rst b/doc/source/user/certificate-validation.rst index 69219a67ed19..5d1eab2531c7 100644 --- a/doc/source/user/certificate-validation.rst +++ b/doc/source/user/certificate-validation.rst @@ -451,9 +451,9 @@ certificate as ``cert_client.pem``. Upload the generated certificates to the key manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order interact with the key manager, the user needs to have a `creator` role. +In order interact with the key manager, the user needs to have a ``creator`` role. -To list all users with a `creator` role, run the following command as an admin: +To list all users with a ``creator`` role, run the following command as an admin: .. code-block:: console @@ -467,7 +467,7 @@ To list all users with a `creator` role, run the following command as an admin: | creator | project_a_creator@Default | | project_a@Default | | False | +---------+-----------------------------+-------+-------------------+--------+-----------+ -To give the `demo` user a `creator` role in the `demo` project, run the +To give the ``demo`` user a ``creator`` role in the ``demo`` project, run the following command as an admin: .. code-block:: console diff --git a/doc/source/user/flavors.rst b/doc/source/user/flavors.rst index 1450d81d73c0..1c36fdaf9cae 100644 --- a/doc/source/user/flavors.rst +++ b/doc/source/user/flavors.rst @@ -25,7 +25,7 @@ Flavor ID Name Name for the new flavor. This property is required. - Historically, names were given a format `XX.SIZE_NAME`. These are typically + Historically, names were given a format ``XX.SIZE_NAME``. These are typically not required, though some third party tools may rely on it. VCPUs diff --git a/doc/source/user/launch-instance-from-volume.rst b/doc/source/user/launch-instance-from-volume.rst index f3c2636d5b2a..970701437a91 100644 --- a/doc/source/user/launch-instance-from-volume.rst +++ b/doc/source/user/launch-instance-from-volume.rst @@ -304,7 +304,7 @@ encryption. .. note:: A bootable encrypted volume can also be created by adding the - `--type ENCRYPTED_VOLUME_TYPE` parameter to the volume create command. + ``--type ENCRYPTED_VOLUME_TYPE`` parameter to the volume create command. For example: .. code-block:: console diff --git a/tox.ini b/tox.ini index 9a6c00691d15..633b6fb32c3c 100644 --- a/tox.ini +++ b/tox.ini @@ -131,6 +131,13 @@ deps = commands = pre-commit run --all-files --show-diff-on-failure codespell +[testenv:sphinx-lint] +description = + Run sphinx lint checks. +deps = pre-commit +commands = + pre-commit run --all-files --show-diff-on-failure sphinx-lint + [testenv:fast8] description = Run style checks on the changes made since HEAD~. For a full run including docs, use 'pep8'