Merge pull request #391 from macartur/improving_sphinx_docs_2017.1rc

Improving sphinx docs 2017.1rc

Author: beraldoleal

docs/conf.py

@@ -389,3 +389,47 @@
 # Order methods before attributes/properties on a class
 autodoc_member_order = 'groupwise'
 todo_include_todos = True
+
+rst_epilog = """
+.. |PacketInReason_v0x04| replace::
+   :class:`~pyof.v0x04.asynchronous.packet_in.PacketInReason`
+
+.. |PortReason_v0x04| replace::
+   :class:`~pyof.v0x04.asynchronous.port_status.PortReason`
+
+.. |FlowRemoved_v0x04| replace::
+   :class:`~pyof.v0x04.asynchronous.flow_removed.FlowRemoved`
+
+.. |TableFeaturePropType_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.common.TableFeaturePropType`
+
+.. |ListOfInstruction_v0x04| replace::
+   :class:`~pyof.v0x04.common.flow_instructions.ListOfInstruction`
+
+.. |GroupType_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.group_mod.GroupType`
+
+.. |ListOfBuckets_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.group_mod.ListOfBuckets`
+
+.. |MeterFlags_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.meter_mod.MeterFlags`
+
+.. |Meter_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.meter_mod.Meter`
+
+.. |MeterBandType_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.meter_mod.MeterBandType`
+
+.. |BandStats_v0x04| replace::
+   :class:`~.v0x04.controller2switch.multipart_reply.BandStats`
+
+.. |ListOfActions_v0x04| replace::
+   :class:`~pyof.v0x04.common.action.ListOfActions`
+
+.. |ListOfOxmHeader_v0x04| replace::
+   :class:`~pyof.v0x04.common.flow_match.ListOfOxmHeader`
+
+.. |Property_v0x04| replace::
+   :class:`~pyof.v0x04.controller2switch.common.Property`
+"""

pyof/foundation/base.py

@@ -119,7 +119,7 @@ def __rxor__(self, other):
     def value(self):
         """Return this type's value.
 
-        The value of an enum, bitmask, etc.
+        Returns: The value of an enum, bitmask, etc.
         """
         if self.isenum():
             if isinstance(self._value, self.enum_ref):
@@ -347,14 +347,14 @@ def get_pyof_version(module_fullname):
                 (e.g.: pyof.v0x01.common.header)
 
         Returns:
-            str: The module version, on the format 'v0x0?' if any. Or None
-                  if there isn't a version on the fullname.
+            str: openflow version.
+                 The openflow 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)
         if matched:
             version = matched.group(2)
-            # module = matched.group(3)
             return version
         return None
 
@@ -386,7 +386,7 @@ def replace_pyof_version(module_fullname, version):
 
     @staticmethod
     def get_pyof_obj_new_version(name, obj, new_version):
-        """Return a class atrribute on a different pyof version.
+        r"""Return a class attribute on a different pyof version.
 
         This method receives the name of a class attribute, the class attribute
         itself (object) and an openflow version.
@@ -399,14 +399,19 @@ def get_pyof_obj_new_version(name, obj, new_version):
         an instance of the new version of the 'obj'.
 
         Example:
-            >> from pyof.v0x01.common.header import Header
-            >> name = 'header'
-            >> obj = Header()
-            >> obj
-            <pyof.v0x01.common.header.Header at 0x...>
-            >> new_version = 'v0x02'
-            >> MetaStruct.get_pyof_new_version(name, obj, new_version)
-            ('header', <pyof.v0x02.common.header.Header at 0x...)
+
+        >>> from pyof.foundation.base import MetaStruct as ms
+        >>> from pyof.v0x01.common.header import Header
+        >>> name = 'header'
+        >>> obj = Header()
+        >>> new_version = 'v0x04'
+        >>> header, obj2 = ms.get_pyof_obj_new_version(name, obj, new_version)
+        >>> header
+        'header'
+        >>> obj.version
+        UBInt8(1)
+        >>> obj2.version
+        UBInt8(4)
 
         Args:
             name (str): the name of the class attribute being handled.
@@ -415,13 +420,14 @@ def get_pyof_obj_new_version(name, obj, new_version):
                 'obj'.
 
         Return:
-            (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
-                passed object is returned without any changes. Also, if the obj
-                is a pyof versioned attribute, but it is already on the right
-                version (same as new_version), then the passed obj is return.
+            (str, obj): Tuple with class name and object instance.
+                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 passed object
+                is returned without any changes. Also, if the obj is a pyof
+                versioned attribute, but it is already on the right version
+                (same as new_version), then the passed obj is return.
         """
         if new_version is None:
             return (name, obj)
@@ -469,6 +475,9 @@ def __eq__(self, other):
 
         Args:
             other (GenericStruct): The struct to be compared with.
+
+        Returns:
+            bool: Returns the result of comparation.
         """
         return self.pack() == other.pack()
 
@@ -488,9 +497,8 @@ def _is_pyof_attribute(obj):
         To be a kytos attribute the item must be an instance of either
         GenericType or GenericStruct.
 
-        returns:
-            True: if the obj is a kytos attribute
-            False: if the obj is not a kytos attribute
+        Returns:
+            bool: Returns TRUE if the obj is a kytos attribute, otherwise False
         """
         return isinstance(obj, (GenericType, GenericStruct))
 

pyof/foundation/basic_types.py

@@ -118,7 +118,7 @@ def __init__(self, dpid=None):
         """Create an instance and optionally set its dpid value.
 
         Args:
-            dpid (str): E.g. 00:00:00:00:00:00:00:01.
+            dpid (str): String with DPID value(e.g. `00:00:00:00:00:00:00:01`).
         """
         super().__init__(value=dpid)
 
@@ -127,7 +127,11 @@ def __str__(self):
 
     @property
     def value(self):
-        """Return dpid value."""
+        """Return dpid value.
+
+        Returns:
+            str: DataPath ID stored by DPID class.
+        """
         return self._value
 
     def pack(self, value=None):
@@ -237,8 +241,7 @@ def __init__(self, address="0.0.0.0/32"):
         """The constructor takes the parameters below.
 
         Args:
-            address (str): IP Address using ipv4.
-                Defaults to '0.0.0.0/32'
+            address (str): IP Address using ipv4. Defaults to '0.0.0.0/32'
         """
         if address.find('/') >= 0:
             address, netmask = address.split('/')
@@ -256,7 +259,7 @@ def pack(self, value=None):
         Args:
             value (str): IP Address with ipv4 format.
 
-        Returns
+        Returns:
             bytes: The binary representation.
 
         Raises: