From b1de27f68a9f80db723c1b3545f95c5c9c8e7e9d Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Mon, 5 Mar 2012 14:33:40 -0500 Subject: fix restructuredtext formatting in docstrings that show up in the developer guide blueprint sphinx-doc-cleanup bug 945160 - Correct parameter declarations, list formatting, cross-references, etc. - We don't need "let" in generate_autodoc_index.sh since we aren't doing math. - Change conf.py to not prefix class and function names with full namespace in generated output to save width on the screen. Change-Id: I9adc8681951913fd291d03e7142146e9d46841df --- nova/virt/driver.py | 32 ++++++++++++++++++-------------- nova/virt/firewall.py | 4 ++-- nova/virt/libvirt/connection.py | 19 ++++++++++--------- nova/virt/vmwareapi/vmops.py | 20 +++++++++++--------- nova/virt/xenapi/vm_utils.py | 18 +++++++++--------- nova/virt/xenapi/vmops.py | 23 ++++++++++++----------- 6 files changed, 62 insertions(+), 54 deletions(-) (limited to 'nova/virt') diff --git a/nova/virt/driver.py b/nova/virt/driver.py index 15fb70f77..9658273db 100644 --- a/nova/virt/driver.py +++ b/nova/virt/driver.py @@ -128,25 +128,29 @@ class ComputeDriver(object): Return the number of virtual machines that the hypervisor knows about. - :note This implementation works for all drivers, but it is - not particularly efficient. Maintainers of the virt drivers are - encouraged to override this method with something more - efficient. + .. note:: + + This implementation works for all drivers, but it is + not particularly efficient. Maintainers of the virt drivers are + encouraged to override this method with something more + efficient. """ return len(self.list_instances()) def instance_exists(self, instance_id): """Checks existence of an instance on the host. + :param instance_id: The ID / name of the instance to lookup + Returns True if an instance with the supplied ID exists on the host, False otherwise. - :note This implementation works for all drivers, but it is - not particularly efficient. Maintainers of the virt drivers are - encouraged to override this method with something more - efficient. + .. note:: - :param instance_id: The ID / name of the instance to lookup + This implementation works for all drivers, but it is + not particularly efficient. Maintainers of the virt drivers are + encouraged to override this method with something more + efficient. """ return instance_id in self.list_instances() @@ -422,7 +426,7 @@ class ComputeDriver(object): host 'H0' and this method would still have been called. The point was that this method isn't called on the host where instances of that group are running (as is the case with - :method:`refresh_security_group_rules`) but is called where references + :py:meth:`refresh_security_group_rules`) but is called where references are made to authorizing those instances. An error should be raised if the operation cannot complete. @@ -436,7 +440,7 @@ class ComputeDriver(object): When this is called, rules have either been added or removed from the datastore. You can retrieve rules with - :method:`nova.db.provider_fw_rule_get_all`. + :py:meth:`nova.db.provider_fw_rule_get_all`. Provider rules take precedence over security group rules. If an IP would be allowed by a security group ingress rule, but blocked by @@ -669,12 +673,12 @@ class ComputeDriver(object): raise NotImplementedError() def get_volume_connector(self, instance): - """ - Get connector information for the instance for attaching to volumes. + """Get connector information for the instance for attaching to volumes. Connector information is a dictionary representing the ip of the machine that will be making the connection and and the name of the - iscsi initiator as follows: + iscsi initiator as follows:: + { 'ip': ip, 'initiator': initiator, diff --git a/nova/virt/firewall.py b/nova/virt/firewall.py index b367aded2..9df036412 100644 --- a/nova/virt/firewall.py +++ b/nova/virt/firewall.py @@ -88,7 +88,7 @@ class FirewallDriver(object): """Create rules to block spoofing and allow dhcp. This gets called when spawning an instance, before - :method:`prepare_instance_filter`. + :py:meth:`prepare_instance_filter`. """ raise NotImplementedError() @@ -362,7 +362,7 @@ class IptablesFirewallDriver(FirewallDriver): self.add_filters_for_instance(instance) def refresh_provider_fw_rules(self): - """See class:FirewallDriver: docs.""" + """See :class:`FirewallDriver` docs.""" self._do_refresh_provider_fw_rules() self.iptables.apply() diff --git a/nova/virt/libvirt/connection.py b/nova/virt/libvirt/connection.py index bcb58b6fb..b41dd452c 100644 --- a/nova/virt/libvirt/connection.py +++ b/nova/virt/libvirt/connection.py @@ -2030,12 +2030,12 @@ class LibvirtConnection(driver.ComputeDriver): block_migration): """Post operation of live migration at destination host. - :params ctxt: security context - :params instance_ref: + :param ctxt: security context + :param instance_ref: nova.db.sqlalchemy.models.Instance object instance object that is migrated. - :params network_info: instance network infomation - :params : block_migration: if true, post operation of block_migraiton. + :param network_info: instance network infomation + :param block_migration: if true, post operation of block_migraiton. """ # Define migrated instance, otherwise, suspend/destroy does not work. dom_list = self._conn.listDefinedDomains() @@ -2064,11 +2064,12 @@ class LibvirtConnection(driver.ComputeDriver): nova.db.sqlalchemy.models.Instance object instance object that is migrated. :return: - json strings with below format. - "[{'path':'disk', 'type':'raw', - 'virt_disk_size':'10737418240', - 'backing_file':'backing_file', - 'disk_size':'83886080'},...]" + json strings with below format:: + + "[{'path':'disk', 'type':'raw', + 'virt_disk_size':'10737418240', + 'backing_file':'backing_file', + 'disk_size':'83886080'},...]" """ disk_info = [] diff --git a/nova/virt/vmwareapi/vmops.py b/nova/virt/vmwareapi/vmops.py index 4574dafdb..f4cbc2506 100644 --- a/nova/virt/vmwareapi/vmops.py +++ b/nova/virt/vmwareapi/vmops.py @@ -87,12 +87,13 @@ class VMWareVMOps(object): Creates a VM instance. Steps followed are: + 1. Create a VM with no disk and the specifics in the instance object - like RAM size. + like RAM size. 2. Create a dummy vmdk of the size of the disk file that is to be - uploaded. This is required just to create the metadata file. + uploaded. This is required just to create the metadata file. 3. Delete the -flat.vmdk file created in the above step and retain - the metadata .vmdk file. + the metadata .vmdk file. 4. Upload the disk file. 5. Attach the disk to the VM by reconfiguring the same. 6. Power on the VM. @@ -335,16 +336,17 @@ class VMWareVMOps(object): _power_on_vm() def snapshot(self, context, instance, snapshot_name): - """ - Create snapshot from a running VM instance. + """Create snapshot from a running VM instance. + Steps followed are: + 1. Get the name of the vmdk file which the VM points to right now. - Can be a chain of snapshots, so we need to know the last in the - chain. + Can be a chain of snapshots, so we need to know the last in the + chain. 2. Create the snapshot. A new vmdk is created which the VM points to - now. The earlier vmdk becomes read-only. + now. The earlier vmdk becomes read-only. 3. Call CopyVirtualDisk which coalesces the disk chain to form a single - vmdk, rather a .vmdk metadata file and a -flat.vmdk disk data file. + vmdk, rather a .vmdk metadata file and a -flat.vmdk disk data file. 4. Now upload the -flat.vmdk file to the image store. 5. Delete the coalesced .vmdk and -flat.vmdk created. """ diff --git a/nova/virt/xenapi/vm_utils.py b/nova/virt/xenapi/vm_utils.py index 5b4d178f8..0da4d6dfb 100644 --- a/nova/virt/xenapi/vm_utils.py +++ b/nova/virt/xenapi/vm_utils.py @@ -94,15 +94,15 @@ KERNEL_DIR = '/boot/guest' class ImageType: - """ - Enumeration class for distinguishing different image types - 0 - kernel image (goes on dom0's filesystem) - 1 - ramdisk image (goes on dom0's filesystem) - 2 - disk image (local SR, partitioned by objectstore plugin) - 3 - raw disk image (local SR, NOT partitioned by plugin) - 4 - vhd disk image (local SR, NOT inspected by XS, PV assumed for - linux, HVM assumed for Windows) - 5 - ISO disk image (local SR, NOT partitioned by plugin) + """Enumeration class for distinguishing different image types + + | 0 - kernel image (goes on dom0's filesystem) + | 1 - ramdisk image (goes on dom0's filesystem) + | 2 - disk image (local SR, partitioned by objectstore plugin) + | 3 - raw disk image (local SR, NOT partitioned by plugin) + | 4 - vhd disk image (local SR, NOT inspected by XS, PV assumed for + | linux, HVM assumed for Windows) + | 5 - ISO disk image (local SR, NOT partitioned by plugin) """ KERNEL = 0 diff --git a/nova/virt/xenapi/vmops.py b/nova/virt/xenapi/vmops.py index e0900cc53..a0d9311f6 100644 --- a/nova/virt/xenapi/vmops.py +++ b/nova/virt/xenapi/vmops.py @@ -99,7 +99,7 @@ def make_step_decorator(context, instance): """Factory to create a decorator that records instance progress as a series of discrete steps. - Each time the decorator is invoked we bump the total-step-count, so after: + Each time the decorator is invoked we bump the total-step-count, so after:: @step def step1(): @@ -112,11 +112,12 @@ def make_step_decorator(context, instance): we have a total-step-count of 2. Each time the step-function (not the step-decorator!) is invoked, we bump - the current-step-count by 1, so after: + the current-step-count by 1, so after:: step1() - the current-step-count would be 1 giving a progress of 1 / 2 * 100 or 50%. + the current-step-count would be 1 giving a progress of ``1 / 2 * + 100`` or 50%. """ instance_uuid = instance['uuid'] @@ -651,18 +652,18 @@ class VMOps(object): Steps involved in a XenServer snapshot: 1. XAPI-Snapshot: Snapshotting the instance using XenAPI. This - creates: Snapshot (Template) VM, Snapshot VBD, Snapshot VDI, - Snapshot VHD + creates: Snapshot (Template) VM, Snapshot VBD, Snapshot VDI, + Snapshot VHD 2. Wait-for-coalesce: The Snapshot VDI and Instance VDI both point to - a 'base-copy' VDI. The base_copy is immutable and may be chained - with other base_copies. If chained, the base_copies - coalesce together, so, we must wait for this coalescing to occur to - get a stable representation of the data on disk. + a 'base-copy' VDI. The base_copy is immutable and may be chained + with other base_copies. If chained, the base_copies + coalesce together, so, we must wait for this coalescing to occur to + get a stable representation of the data on disk. 3. Push-to-glance: Once coalesced, we call a plugin on the XenServer - that will bundle the VHDs together and then push the bundle into - Glance. + that will bundle the VHDs together and then push the bundle into + Glance. """ template_vm_ref = None -- cgit