Fix multiple references warnings using v0x01

This commit will fix sphinx warnings with more than one target found.

Author: macartur

pyof/foundation/base.py

@@ -5,9 +5,10 @@
 structs. You can realize that when you see a message class definition.
 
 A **struct** here is a group of basic attributes and/or struct attributes (i.e.
-:class:`~.common.header.Header`). A **message** here is like a struct, but all
-messages have a header attribute (i.e.
-:class:`~.asynchronous.packet_in.PacketIn`).
+:class:`~pyof.v0x01.common.header.Header`). A **message** here is like a
+struct, but all messages have a header attribute (i.e.
+:class:`~pyof.v0x01.asynchronous.packet_in.PacketIn`).
+
 
 The main classes of this module are :class:`GenericStruct`,
 :class:`GenericMessage`, :class:`GenericBitMask` and :class:`GenericType`.
@@ -49,9 +50,9 @@ def __init__(self, value=None, enum_ref=None):
         """The constructor takes the optional parameters below.
 
         Args:
-            value: The type's value.
-            enum_ref (:class:`type`): If :attr:`value` is from an Enum, specify
-                its type.
+            value : The type's value.
+            enum_ref (type): If :attr:`value` is from an Enum, specify
+                             its type.
         """
         self._value = value
         self.enum_ref = enum_ref
@@ -219,10 +220,10 @@ def is_valid(self):
             return False
 
     def isenum(self):
-        """Test whether it is an :class:`~Enum`.
+        """Test whether it is an :class:`~enum.Enum`.
 
         Returns:
-            bool: Whether it is an :class:`~Enum`.
+            bool: Whether it is an :class:`~enum.Enum`.
         """
         return self.enum_ref and issubclass(self.enum_ref, (Enum, IntEnum))
 
@@ -346,8 +347,8 @@ def get_pyof_version(module_fullname):
                 (e.g.: pyof.v0x01.common.header)
 
         Returns:
-            version (str): The module version, on the format 'v0x0?' if any. Or
-            None (None): If there isn't a version on the fullname.
+            str : The module version, on the format 'v0x0?' if any. Or None
+                  if there isn't a version on the fullname.
         """
         ver_module_re = re.compile(r'(pyof\.)(v0x\d+)(\..*)')
         matched = ver_module_re.match(module_fullname)
@@ -366,15 +367,16 @@ def replace_pyof_version(module_fullname, version):
 
         Args:
             module_fullname (str): The fullname of the module
-                (e.g.: pyof.v0x01.common.header)
+                                   (e.g.: pyof.v0x01.common.header)
             version (str): The version to be 'inserted' on the module fullname.
 
         Returns:
-            None (None): if the requested version is the same as the one of the
-                module_fullname or if the module_fullname is not a 'OF version'
-                specific module.
-            new_module_fullname (str): The new module fullname, with the
-                replaced version, on the format "pyof.v0x01.common.header".
+            str  : module fullname
+                   The new module fullname, with the replaced version,
+                   on the format "pyof.v0x01.common.header". If the requested
+                   version is the same as the one of the module_fullname or if
+                   the module_fullname is not a 'OF version' specific module
+                   the return is None.
         """
         module_version = MetaStruct.get_pyof_version(module_fullname)
         if not module_version or module_version == version:
@@ -413,7 +415,7 @@ def get_pyof_obj_new_version(name, obj, new_version):
                 'obj'.
 
         Return:
-            (name, obj): A tuple in which the first item is the name of the
+            (str, obj): A tuple in which the first item is the name of the
                 class attribute (the same that was passed), and the second item
                 is a instance of the passed class attribute. If the class
                 attribute is not a pyof versioned attribute, then the same
@@ -655,8 +657,9 @@ def is_valid(self):
 
         This method will check whether all struct attributes have a proper
         value according to the OpenFlow specification. For instance, if you
-        have a struct with an attribute of type :class:`UBInt8()`
-        and you assign a string value to it, this method will return False.
+        have a struct with an attribute of type
+        :class:`~pyof.foundation.basic_types.UBInt8` and you assign a string
+        value to it, this method will return False.
 
         Returns:
             bool: Whether the struct is valid.

pyof/foundation/basic_types.py

@@ -401,9 +401,11 @@ def is_broadcast(self):
 class BinaryData(GenericType):
     """Class to create objects that represent binary data.
 
-    This is used in the ``data`` attribute from :class:`.PacketIn` and
-    :class:`.PacketOut` messages. Both the :meth:`pack` and :meth:`unpack`
-    methods will return the binary data itself. :meth:`get_size` method will
+    This is used in the ``data`` attribute from
+    :class:`~pyof.v0x01.asynchronous.packet_in.PacketIn` and
+    :class:`~pyof.v0x01.controller2switch.packet_out.PacketOut` messages.
+    Both the :meth:`pack` and :meth:`unpack` methods will return the
+    binary data itself. :meth:`get_size` method will
     return the size of the instance using Python's :func:`len`.
     """
 

pyof/v0x01/asynchronous/error_msg.py

@@ -170,7 +170,7 @@ class ErrorMsg(GenericMessage):
     This message does not contain a body in addition to the OpenFlow Header.
     """
 
-    #: :class:`~.header.Header`: OpenFlow Header
+    #: :class:`~pyof.v0x01.common.header.Header`: OpenFlow Header
     header = Header(message_type=Type.OFPT_ERROR)
     error_type = UBInt16(enum_ref=ErrorType)
     code = UBInt16()
@@ -181,10 +181,9 @@ def __init__(self, xid=None, error_type=None, code=None, data=b''):
 
         Args:
             xid (int): To be included in the message header.
-            error_type (ErrorType): Error type.
-            code (Enum): Error code.
-            data (:func:`bytes` or packable): Its content is based on the error
-                type and code.
+            error_type (:class:`ErrorType`): Error type.
+            code (enum.IntEnum): Error code.
+            data (bytes): Its content is based on the error type and code.
         """
         super().__init__(xid)
         self.error_type = error_type
@@ -198,7 +197,7 @@ def pack(self, value=None):
         After that, :attr:`data`'s value is restored.
 
         Returns:
-            bytes: The binary representation.
+            bytes : The binary representation.
         """
         if value is None:
             data_backup = None
@@ -217,7 +216,18 @@ def pack(self, value=None):
             raise PackException(msg)
 
     def unpack(self, buff, offset=0):
-        """Unpack binary data into python object."""
+        """Unpack *buff* into this object.
+
+        This method will convert a binary data into a readable value according
+        to the attribute format.
+
+        Args:
+            buff (bytes): Binary buffer.
+            offset (int): Where to begin unpacking.
+
+        Raises:
+            :exc:`~.exceptions.UnpackException`: If unpack fails.
+        """
         super().unpack(buff, offset)
         CodeClass = ErrorType(self.error_type).get_class()
         self.code = CodeClass(self.code)

pyof/v0x01/asynchronous/flow_removed.py

@@ -29,9 +29,9 @@ class FlowRemovedReason(IntEnum):
 class FlowRemoved(GenericMessage):
     """Flow removed (datapath -> controller)."""
 
-    #: :class:`~.header.Header`: OpenFlow Header
+    #: :class:`~pyof.v0x01.common.header.Header`: OpenFlow Header
     header = Header(message_type=Type.OFPT_FLOW_REMOVED)
-    #: :class:`~.flow_match.Match`: OpenFlow Header
+    #: :class:`~pyof.v0x01.common.flow_match.Match`: OpenFlow Header
     match = Match()
     cookie = UBInt64()
 
@@ -56,10 +56,11 @@ def __init__(self, xid=None, match=None, cookie=None, priority=None,
 
         Args:
             xid (int): OpenFlow Header's xid.
-            match (Match): Fields' description.
+            match (~pyof.v0x01.common.flow_match.Match): Fields' description.
             cookie (int): Opaque controller-issued identifier.
             priority (int): Priority level of flow entry.
-            reason (FlowRemovedReason): Why the flow was removed.
+            reason (~pyof.v0x01.asynchronous.flow_removed.FlowRemovedReason):
+                Why the flow was removed.
             duration_sec (int): Time the flow was alive in seconds.
             duration_nsec (int): Time the flow was alive in nanoseconds in
                 addition to duration_sec.

pyof/v0x01/asynchronous/packet_in.py

@@ -32,7 +32,7 @@ class PacketInReason(IntEnum):
 class PacketIn(GenericMessage):
     """Packet received on port (datapath -> controller)."""
 
-    #: :class:`~.header.Header`: OpenFlow Header
+    #: :class:`~pyof.v0x01.common.header.Header`: OpenFlow Header
     header = Header(message_type=Type.OFPT_PACKET_IN)
     buffer_id = UBInt32()
     total_len = UBInt16()
@@ -51,7 +51,8 @@ def __init__(self, xid=None, buffer_id=NO_BUFFER, total_len=None,
             buffer_id (int): ID assigned by datapath.
             total_len (int): Full length of frame.
             in_port (int): Port on which frame was received.
-            reason (PacketInReason): The reason why the packet is being sent
+            reason (~pyof.v0x01.asynchronous.packet_in.PacketInReason):
+                The reason why the packet is being sent
             data (bytes): Ethernet frame, halfway through 32-bit word, so the
                 IP header is 32-bit aligned. The amount of data is inferred
                 from the length field in the header. Because of padding,

pyof/v0x01/asynchronous/port_status.py

@@ -32,7 +32,7 @@ class PortReason(IntEnum):
 class PortStatus(GenericMessage):
     """A physical port has changed in the datapath."""
 
-    #: :class:`~.header.Header`: OpenFlow Header
+    #: :class:`~pyof.v0x01.common.header.Header`: OpenFlow Header
     header = Header(message_type=Type.OFPT_PORT_STATUS)
     reason = UBInt8(enum_ref=PortReason)
     #: Align to 32-bits.
@@ -44,7 +44,8 @@ def __init__(self, xid=None, reason=None, desc=None):
 
         Args:
             xid (int): Header's xid.
-            reason (PortReason): Addition, deletion or modification.
+            reason (~pyof.v0x01.asynchronous.port_status.PortReason):
+                Addition, deletion or modification.
             desc (PhyPort): Port description.
         """
         super().__init__(xid)

pyof/v0x01/common/action.py

@@ -67,7 +67,8 @@ def __init__(self, action_type=None, length=None):
         """The following constructor parameters are optional.
 
         Args:
-            action_type (ActionType): The type of the action.
+            action_type (~pyof.v0x01.common.action.ActionType):
+                The type of the action.
             length (int): Length of action, including this header.
         """
         super().__init__()
@@ -122,7 +123,8 @@ def __init__(self, port=None, max_length=UBINT16_MAX_VALUE):
         """The following constructor parameters are optional.
 
         Args:
-            port (:class:`Port` or :class:`int`): Output port.
+            port (:class:`~pyof.v0x01.common.phy_port.Port` or :class:`int`):
+                Output port.
             max_length (int): Max length to send to controller.
         """
         super().__init__(action_type=ActionType.OFPAT_OUTPUT, length=8)
@@ -218,7 +220,8 @@ def __init__(self, action_type=None, dl_addr=None):
         """The following constructor parameters are optional.
 
         Args:
-            action_type (ActionType): :attr:`~ActionType.OFPAT_SET_DL_SRC` or
+            action_type (~pyof.v0x01.common.action.ActionType):
+                :attr:`~ActionType.OFPAT_SET_DL_SRC` or
                 :attr:`~ActionType.OFPAT_SET_DL_DST`.
             dl_addr (:class:`~.HWAddress`): Ethernet address.
                 Defaults to None.
@@ -238,7 +241,8 @@ def __init__(self, action_type=None, nw_addr=None):
         """The following constructor parameters are optional.
 
         Args:
-            action_type (ActionType): :attr:`~ActionType.OFPAT_SET_NW_SRC` or
+            action_type (~pyof.v0x01.common.action.ActionType):
+                :attr:`~ActionType.OFPAT_SET_NW_SRC` or
                 :attr:`~ActionType.OFPAT_SET_NW_DST`.
             nw_addr (int): IP Address.
         """
@@ -263,7 +267,8 @@ def __init__(self, action_type=None, nw_tos=None):
         """The following constructor parameters are optional.
 
         Args:
-            action_type (ActionType): :attr:`~ActionType.OFPAT_SET_NW_SRC` or
+            action_type (~pyof.v0x01.common.action.ActionType):
+                :attr:`~ActionType.OFPAT_SET_NW_SRC` or
                 :attr:`~ActionType.OFPAT_SET_NW_DST`.
             nw_tos (int): IP ToS (DSCP field, 6 bits).
         """
@@ -284,7 +289,8 @@ def __init__(self, action_type=None, tp_port=None):
         """The following constructor parameters are optional.
 
         Args:
-            action_type (ActionType): :attr:`~ActionType.OFPAT_SET_TP_SRC` or
+            action_type (~pyof.v0x01.common.action.ActionType):
+                :attr:`~ActionType.OFPAT_SET_TP_SRC` or
                 :attr:`~ActionType.OFPAT_SET_TP_DST`.
             tp_port (int): TCP/UDP/other port to set.
         """

pyof/v0x01/common/header.py

@@ -77,7 +77,7 @@ def __init__(self, message_type=None, length=None, xid=None):
         """The constructor takes the optional parameters below.
 
         Args:
-            message_type (Type): Type of the message.
+            message_type (~pyof.v0x01.common.header.Type): Type of the message.
             xid (int): ID of the message. Defaults to a random integer.
             length (int): Length of the message, including the header itself.
         """

pyof/v0x01/common/phy_port.py

@@ -133,13 +133,14 @@ class PhyPort(GenericStruct):
 
     The port_no field is a value the datapath associates with a physical port.
     The hw_addr field typically is the MAC address for the port;
-    :data:`.OFP_ETH_ALEN` is 6. The name field is a
+    :data:`OFP_ETH_ALEN` is 6. The name field is a
     null-terminated string containing a human-readable name for the interface.
-    The value of :data:`.OFP_MAX_PORT_NAME_LEN` is 16.
+    The value of :data:`OFP_MAX_PORT_NAME_LEN` is 16.
 
     :attr:`curr`, :attr:`advertised`, :attr:`supported` and :attr:`peer` are
-    bitmaps of :class:`PortFeatures` enum values that describe features. If
-    unsupported or unavailable, set all bits to zero.
+    bitmaps of :class:`~pyof.v0x01.common.phy_port.PortFeatures` enum values
+    that describe features. If unsupported or unavailable, set all bits to
+    zero.
     """
 
     port_no = UBInt16()
@@ -161,12 +162,17 @@ def __init__(self, port_no=None, hw_addr=None, name=None, config=None,
             port_no (int): Port number.
             hw_addr (HWAddress): Hardware address.
             name(str): Null-terminated name.
-            config (PortConfig): Bitmap of OFPPC* flags.
-            state (PortState): Bitmap of OFPPS* flags.
-            curr (PortFeatures): Current features.
-            advertised (PortFeatures): Features being advertised by the port.
-            supported (PortFeatures): Features supported by the port.
-            peer (PortFeatures): Features advertised by peer.
+            config (~pyof.v0x01.common.phy_port.PortConfig):
+                Bitmap of OFPPC* flags.
+            state (~pyof.v0x01.common.phy_port.PortState):
+                Bitmap of OFPPS* flags.
+            curr (~pyof.v0x01.common.phy_port.PortFeatures): Current features.
+            advertised (~pyof.v0x01.common.phy_port.PortFeatures):
+                Features being advertised by the port.
+            supported (~pyof.v0x01.common.phy_port.PortFeatures):
+                Features supported by the port.
+            peer (~pyof.v0x01.common.phy_port.PortFeatures):
+                Features advertised by peer.
         """
         super().__init__()
         self.port_no = port_no
@@ -184,7 +190,9 @@ class ListOfPhyPorts(FixedTypeList):
     """List of PhyPorts.
 
     Represented by instances of PhyPort and used on
-    :class:`.FeaturesReply`/:class:`.SwitchFeatures` objects.
+    :class:`pyof.v0x01.common.phy_port.FeaturesReply`/
+    :class:`pyof.v0x01.controller2switch.features_reply.SwitchFeatures`
+    objects.
     """
 
     def __init__(self, items=None):

pyof/v0x01/common/queue.py

@@ -58,7 +58,8 @@ def __init__(self, queue_property=None, length=None):
         """The contructor takes the paremeters below.
 
         Args:
-            queue_property (QueueProperties): The queue property.
+            queue_property (~pyof.v0x01.common.queue.QueueProperties):
+                The queue property.
             length (int): Length of property, including this header.
         """
         super().__init__()
@@ -81,8 +82,8 @@ def __init__(self, queue_id=None, length=None, properties=None):
         Args:
             queue_id (int): ID of the specific queue.
             length (int): Length in bytes of this queue desc.
-            properties(ListOfProperties): Queue's list of properties. Default
-                is an empty list.
+            properties(~pyof.v0x01.common.queue.ListOfProperties):
+                Queue's list of properties. Default is an empty list.
         """
         super().__init__()
         self.queue_id = queue_id